Introduction

Zoho Desk APIs facilitate integration with other Zoho applications and third-party tools by adhering to RESTful principles. These APIs enable you to programmatically fetch and edit data in the different modules in Zoho Desk, such as Tickets, Contacts, Accounts and so on. All the APIs follow HTTP rules and error codes. To keep yourself updated about the changes in our APIs, follow the Zoho Desk Developer APIs forum.

API Root Endpoint

desk.zoho.com/api/v1

Getting Started

All Zoho Desk APIs require these two mandatory fields in the header.

Authorization - Authentication request token
orgId -ID of the organization to access. All API endpoints except /organizations mandatorily require the orgId.

Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

HTTP Methods

Zoho Desk APIs enable data manipulation and retrieval through different HTTP methods.

Method	Purpose
GET	Retrieve resources
POST	Create resources and perform resource actions
PUT	Update resources
PATCH	Partially update resources
DELETE	Delete resources

Using the GET method, you can get a list of resources or details of a particular instance of a resource.
To get a list of tickets

$ curl -X GET https://desk.zoho.com/api/v1/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

To get the details of a ticket referred to by a specified ticket_id

$ curl -X GET https:// desk.zoho.com/api/v1/tickets/903000000000099
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Errors

Zoho Desk uses HTTP status codes to indicate success or failure of API calls. Status codes in the 2xx range indicate success, 4xx range indicate error in the information provided, and 5xx range indicate server side errors. The following table lists some commonly used HTTP status codes.

HTTP Status Codes

Status Code	Description
200	OK
201	Created
204	No content
400	Bad request
401	Unauthorized
403	Forbidden (Unauthorised access)
404	URL not found
405	Method not allowed (Method called is not supported for the API invoked)
413	Payload Too Large
415	Unsupported Media Type
422	Unprocessable Entity
429	Too Many Requests
500	Internal error

Besides HTTP status codes and their corresponding error messages, error responses for Zoho Desk APIs also include a machine-parsable errorCode param to simplify error handling.

The different errorCodes and their uses are described below.

UNAUTHORIZED

This errorCode value appears if the authentication token in the API request is invalid

INVALID_OAUTH

This errorCode value appears if the OAuthToken is invalid or expired.

SCOPE_MISMATCH

This errorCode value appears if the OAuthToken does not contain the scope required to perform the operation.

OAUTH_ORG_MISMATCH

This errorCode value appears if the user chooses a different organization while generating the OAuthToken instead of the organization in which they want to perform the operation.

FORBIDDEN

This errorCode value appears if the user does not have all the permissions required to access the resource.

LICENSE_ACCESS_LIMITED

This errorCode value appears if the user is unable to perform an action due to the limitations of the Zoho Desk edition in use

The possible values for the feature key are

AGENTS
LIGHT_AGENTS
TEAM

The possible values for the editionType key are

FREE
PROFESSIONAL
ENTERPRISE

URL_NOT_FOUND

This errorCode value appears if the URL provided is invalid or does not exist.

METHOD_NOT_ALLOWED

This errorCode value appears if the method in the API request is known by the server but disabled for the API requested.

RESOURCE_SIZE_EXCEEDED

This errorCode value appears if the size of the resource exceeds the limit defined by the server.

UNSUPPORTED_MEDIA_TYPE

This errorCode value appears if the server refuses the request as a result of receiving the input in an unsupported format.

INVALID_DATA

This errorCode value appears if there are inaccuracies, such as duplicate entries or invalid IDs, in the data given by the user. The type of inaccuracy is identified by the errorType param.

The possible values for the errorType key are:

invalid - the field contains an invalid value
duplicate - the field contains a value that already exists
missing - the field does not contain a value

The field that contains the inaccurate value is returned in the fieldName param, which is represented in the JSON Pointer convention

UNPROCESSABLE_ENTITY

This errorCode value appears if the input does not fulfil the conditions necessary for successfully executing the API.

ONLY_LIVECHAT_USER

This errorCode value appears if the API request tries to remove the last user remaining in a department that has live chat enabled

INTEGRATION_ADMIN_ERROR

This errorCode value appears if the API request tries to deactivate a user who has enabled integrations in the help desk portal

The integration param returns the integration the user enabled in the portal. The possible values are :

LIVECHAT

THRESHOLD_EXCEEDED

This errorCode value appears if the user sends too many requests within a given amount of time ("rate limiting").

INTERNAL_SERVER_ERROR

This errorCode value appears if the server encounters an unexpected condition that prevents it from fulfilling the request.

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/700000007942
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60"

Response Example

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{ "message": "Error while Processing Request." }

UnAuthenticatedErrorResponse

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{ "errorCode": "UNAUTHORIZED", "message": "You are not authorized to perform this operation." }

Oauth Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{ "message": "The OauthToken is invalid or has expired.", "errorCode": "INVALID_OAUTH" }

ScopeMisMatch Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{ "errorCode": "SCOPE_MISMATCH", "message": "The OAuthToken does not contain the scope required to perform this operation." }

OAuth Org Mismatch Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{ "errorCode": "OAUTH_ORG_MISMATCH", "message": "The OAuthToken is not valid for specified organization." }

Forbidden Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{ "errorCode": "FORBIDDEN", "message": "You are not authorized to access this resource." }

LicenseAccessLimited Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{ "maxAllowedEntity": "10", "feature": "AGENTS", "errorCode": "LICENSE_ACCESS_LIMITED", "editionType": "FREE", "message": "Your Zoho Desk Edition does not support this feature/operation.", "isTrial": false }

Url Not Found Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{ "errorCode": "URL_NOT_FOUND", "message": "The URL you requested could not be found." }

Method Not Allowed Error Response

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8

{ "errorCode": "METHOD_NOT_ALLOWED", "message": "This HTTP method is not allowed on this URL." }

Resource Size Exceeded Error Response

HTTP/1.1 413 Payload Too Large
Content-Type: application/json;charset=UTF-8

{ "errorCode": "RESOURCE_SIZE_EXCEEDED", "message": "Attachment size is too large. The maximum size supported is 20 MB." }

Unsupported Media Type Error Response

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json;charset=UTF-8

{ "errorCode": "UNSUPPORTED_MEDIA_TYPE", "message": "The given content type is not supported. Please provide the input Content-Type as application/json" }

Invalid Data Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{ "errorCode": "INVALID_DATA", "message": "The data does not comply to the validation restrictions defined.", "errors": [ { "fieldName": "/contactId", "errorType": "invalid" }, { "fieldName": "/departmentId", "errorType": "invalid" } ] }

Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{ "errorCode": "UNPROCESSABLE_ENTITY", "message": "The value passed for the 'from' query parameter is invalid." }

Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{ "errorCode": "ONLY_LIVECHAT_USER", "departmentIds": [ "1301000000033146" ], "message": "The given user is the only user with chat enabled in the department" }

Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{ "errorCode": "INTEGRATION_ADMIN_ERROR", "message": "The given user is the admin of the following integration", "integration": "LIVECHAT" }

Threshold Exceeded Error Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8

{ "errorCode": "THRESHOLD_EXCEEDED", "message": "The maximum number of API calls that can be made per minute has been exceeded." }

Internal Server Error Response

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8

{ "errorCode": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred while performing this operation." }

Pagination

In Zoho Desk, you can fetch multiple resources using listing APIs, such as list tickets , list agents and list departments and so on. The retrieval and arrangement of these resources on end-users' screen is called pagination. Pagination in listing APIs is made possible by two parameters: from and limit

Attributes	Description
from	from indicates the offset from which the records is to be fetched the default value of from parameter is 1
limit	limit indicates the number of records the API must fetch. The default value of limit will be 10. A single API request can fetch a maximum of 50 resources. However, some APIs support higher limits, which is mentioned in the API document, wherever applicable

The paginated responses are retrieved in the form of JSON objects that contain a key called data and a JSON array of resources (objects) as the value.

Request Example with pagination

$ curl -X GET 'https://desk.zoho.com/api/v1/accounts?from=1&limit=1'
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
-H "featureFlags:multiLayout,ticketTeam"

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"data" : [ { 
"website" : "112121",
"accountName" : "Admin Account",
"phone" : "121212",
"webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
"createdTime" : "2015-02-16T16:57:44.000Z",
"zohoCRMAccount" : {
"id" : "32754000000537001"
},
"customerHappiness" : {
"badPercentage" : "30",
"okPercentage" : "30",
"goodPercentage" : "40"
},
"id" : "1892000000052077",
"email" : "admin@zylker.com"
} ]
}

Include

Zoho Desk enables you to retrieve different related resources through a single API request, which is made possible by the include query param. This query param takes a comma separated list of values corresponding to the API.

Conventions

Always ignore undocumented fields or enum values present in the api response.These fields could be either experimental or deprecated.
Data fields in tickets, contacts, accounts, tasks etc are dynamic. This is due to security field filtering applied for user profile. Hence when coding with data from these api always consider them as dynamic.

Compatibility

Backwards Compatibility on api changes is always maintained. Minor api changes like field, URL, query param deprecation will be notified via forum with a transistion period. Support will be revoked after the end of transition period. Only major api interface change will involve the version number in the URL to change.

Authentication(OAuth)

Zoho Desk's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization. This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. Each API request must include an OAuthToken to retrieve any resource from your Zoho Desk portal.

Why should we use OAuth2.0?
How OAuth2.0 works?
Terminologies
Tokens
Scopes

To view a sample reference code in Java to help you understand the OAuth authorization flow for Zoho Desk Rest APIs, click here.

Why should we use OAuth2.0?

Clients are not required to support password authentication or store user credentials.
Clients gain delegated access, i.e., access only to resources authenticated by the user.
Users can revoke the client's delegated access anytime.
OAuth2.0 access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.

How OAuth2.0 works?

Terminologies

The following are some terms you need to know before you start using the Zoho Desk APIs.

Protected resources:

The Zoho Desk resources, such as Tickets, Contacts, Tasks, etc.

Resource server:

The Zoho Desk server that hosts protected resources.

Resource owner:

Any end-user of your account, who can grant access to the protected resources.

Client:

An application that sends requests to the resource server to access the protected resources on behalf of the end-user.

Client ID:

The consumer key generated from the connected application.

Client Secret:

The consumer secret generated from the connected application.

Authentication server:

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the Zoho Desk authorization server.

Authentication code:

The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens..

Tokens

Access Token:

A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to Zoho Desk APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.

Refresh Token:

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Sample Success Response

{ "access_token": "1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6", "refresh_token": "1000.aed4288cd9cfb2d63d093faef1b98890.2f4aa58ddadbec9fbbfd683805da839b", "token_type": "Bearer", "expires_in": 3600 }

Step 1: Register your Application

First, register your app in Zoho's Developer Console, which you can access here.

Choose a client type

Java Script: Applications that run exclusively on a browser and are independent of a web server.
Web Based: Applications that are clients running on a dedicated HTTP server.
Mobile: Applications that are installed on smart phones and tablets.
Non-browser Mobile Applications: Applications for devices without browser provisioning such as smart TVs and printers.
Self Client: If your application is a stand-alone application that performs only back-end jobs like data-sync (without any manual intervention).

For more details, refer to OAuth Overview.

Choose Web based client and Enter the following details:

Client Name: The name of your application you want to register with Zoho.
Homepage URL: The URL of your web page.
Authorized Redirect URIs: A valid URL of your application to which Zoho Accounts redirects you with a grant token(code) after successful authentication.

On successful registration, you will be provided with a client ID and a client secret. These are your OAuth credentials.

Step2: Making the Authorization Request

To use the Zoho Desk APIs, the user must authenticate the application to make API calls on their behalf with an access token.

The access token, in return, must be obtained from a grant token (authorization code). The Zoho Desk APIs use the authorization code grant type to provide access to protected resources.

There are two ways in which you can generate the grant token based on the client type.

Web-based application
Self-client

Web-based application

Web-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. For this client-type, you must use redirection-based code generation. In this authorization flow, obtain an authorization grant by invoking the authorization URI, that contains the parameters listed in the table below. Refer to the example to understand how to construct this authorization URI.

Parameter	Description
client_id	Client ID generated after registering the client.
response_type	`"code"`
redirect_uri	Redirect URI mentioned while registering the client.
scope	The various scopes associated with Zoho Desk.You can use the list of scopes as per your requirement
access_type	`"offline"/"online"`. In cases where refresh tokens can't be stored, use online access_type. The default will be online
state	State is an opaque value used by the client to maintain state between the request and callback.

After you invoke the authorization URI, a "user-consent" page opens.

When the user clicks Accept:

The application gets authorized. The grant token sent as a parameter in the redirect_uri.

A back-end script from your end needs to store the following details from the above URL.

code={grant_token} - This is used to generate access and refresh tokens.
location={domain} - This tells you the domain of the user from which you have to make API calls.
accounts-server={accounts_URL} - This is your accounts URL which you have to use to generate access and refresh tokens.

The application exchanges the authorization code for an access token.

When the user clicks Reject:

The browser redirects to the redirect URI with the parameter error=access_denied, and your application is denied access to the user's data in Zoho Desk.

`Note:`

The grant token is valid only for one minute.

Generating OAuth Tokens Using Self Client

Use this method to generate the grant token if your application does not have a domain and a redirect URL.
You can also use this option when your application is a standalone server-side application performing a back-end job.

Go to Zoho Developer Console.
Choose Self Client from the list of client types, and click Create Now.
Click OK in the pop up to enable a self client for your account.
Now, your client ID and client secret are displayed under the Client Secret tab.
Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details.
Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
Enter a description and click Generate.
The generated code for the specified scope is displayed. Copy the grant token.

`Note`:

Generating the grant token is a one-time process, provided you generate the access and refresh tokens within the time the grant token is valid for.

Authorization Grant API Url

GET https://accounts.zoho.com/oauth/v2/auth

Query Params

?response_type=code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&state=-5466400890088961855

Step 3: Generating Tokens

Invoke a URL in the following format to exchange the authorization code (obtained at the end of the previous step) with an OAuthToken.

Parameter	Description
code	Authorization code obtained after generating the grant token.
client_id	Client ID obtained after registering the client.
client_secret	Client secret obtained after registering the client.
grant_type	`"authorization_code"`
redirect_uri	Redirect URI mentioned while registering the client.

After invoking the URL, you will be presented with an access token, which you must include in all API calls.

`Note:`

Each access token is valid for only an hour and used only for the operations defined in the scope.

Refresh token does not expire. Use it to refresh access tokens when they expire.

You can only generate a maximum of five refresh tokens in a minute.

Access Token API Url

POST https://accounts.zoho.com/oauth/v2/token

Query Params

?code=1000.fadbca4c2be2f08b0ce82a54f4313.ba5325853af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/oauthgrant

Response Example

Step 4: Refreshing your Access Tokens

Access tokens generally expire in one hour, which means a new access token has to be generated to keep the process going. You can eliminate the need to perform the entire procedure to generate access tokens, by using refresh tokens. Once the access token expires, the refresh token can be used to generate a new access token.

Refresh token can be obtained only when access_type is set to offline while creating the access token.

Refer to the example to understand how an access token can be obtained using the refresh token.

`Note:`

A "User" in an organization can have a maximum of 20 refresh tokens. And each refresh token can have a maximum of 30 active access tokens (non expired).
When a user creates a 31st access token, the system deletes the first created access token. Similarly, when the user creates the 21st refresh token, the system deletes the first created refresh token.
You can only generate a maximum of five refresh tokens in a minute.
We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your Desk account.

Access Token From Refresh token API Url

POST https://accounts.zoho.com/oauth/v2/token

Query Params

?refresh_token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&grant_type=refresh_token

Response Example

{ "access_token": "1000.2d4437b4f862641d76dedac5f95a3f8a.fac6eb7129da540de1d53b06562e744d", "token_type": "Bearer", "expires_in": 3600 }

Step 5: Revoking Tokens

If you want to revoke your refresh token, Make a POST request with the following URL:

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Refer to the example to understand how a refresh token can be revoked.

Revoking Token API Url

POST https://accounts.zoho.com/oauth/v2/token/revoke

Query Params

?token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e

Using OAuth Token In API Calls

To invoke Zoho Desk's APIs, pass the access token in the Authorization parameter in the header, as shown in the example.

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Response Example

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8

{ "phone": "1 888 900 9646", "assigneeId": "1892000000056007", "subject": "Welcome to Zoho Desk. You've got a sample Request!", "timeEntryCount": "3", "resolution": null, "id": "1892000000042034", "closedTime": null, "webUrl": "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "description": "Hello! Welcome to Zoho Desk.

I am glad to assist you deliver more happiness in every support request.Thank you for choosing Zoho Desk,
Lawrence
Customer Support Executive", "priority": "High", "customerResponseTime": "2017-11-04T11:21:07.912Z", "approvalCount": "1", "dueDate": "2017-11-05T16:16:16.000Z", "customFields": { "location": "Asia" }, "createdTime": "2017-11-04T11:21:07.000Z", "status": "Open", "modifiedTime": "2017-11-04T13:16:14.000Z", "ticketNumber": "101", "commentCount": "1", "attachmentCount": "1", "productId": null, "category": "Customer Request", "contactId": "1892000000042032", "email": "steve@zylker.com", "taskCount": "1", "subCategory": "Feature Request", "classification": null, "threadCount": "121", "departmentId": "1892000000006907", "channel": "Email" }

OAuth Scopes

The various scopes accessible using Zoho Desk's APIs are as follows:

ScopeName	Description
Desk.tickets.ALL	Grants read and write access to tickets and related data.
Desk.tickets.READ	Grants read access to tickets and related data.
Desk.tickets.WRITE	Grants write access to tickets.
Desk.tickets.UPDATE	Grants update access to tickets and related data.
Desk.tickets.CREATE	Grants access to create tickets
Desk.tickets.DELETE	Grants access to delete tickets
Desk.contacts.READ	Grants read access to contacts, accounts and related data
Desk.contacts.WRITE	Grants write access to contacts, accounts and related data
Desk.contacts.UPDATE	Grants update access to contacts, accounts and related data
Desk.contacts.CREATE	Grants access to create contacts and accounts
Desk.tasks.ALL	Grants read and write access to tasks and related data
Desk.tasks.WRITE	Grants write access to tasks and related data
Desk.tasks.READ	Grants read access to tasks and related data
Desk.tasks.CREATE	Grants access to create tasks
Desk.tasks.UPDATE	Grants update access to tasks and related data
Desk.tasks.DELETE	Grants access to delete tasks
Desk.basic.READ	Grants read access to basic data, such as organizations, agents and departments
Desk.basic.CREATE	Grants access to create basic data, such as organizations, agents and departments
Desk.settings.ALL	Grants read and write access to settings data
Desk.settings.WRITE	Grants write access to settings data
Desk.settings.READ	Grants read access to settings data
Desk.settings.CREATE	Grants access to create new settings data
Desk.settings.UPDATE	Grants access to update existing settings data
Desk.settings.DELETE	Grants access to delete settings data
Desk.search.READ	Grants access to search for data
Desk.events.ALL	Grants read and write access to the events subscription
Desk.events.READ	Grants read access to the events subscription
Desk.events.WRITE	Grants write access to the events subscription
Desk.events.CREATE	Grants access to create events subscription
Desk.events.UPDATE	Grants update access to the events subscription
Desk.events.DELETE	Grants delete access to the events subscription
Desk.articles.READ	Grants read access to articles
Desk.articles.CREATE	Grants access to create articles
Desk.articles.UPDATE	Grants update access to articles
Desk.articles.DELETE	Grants delete access to articles

Organization Binding

Any OAuth token generated is linked to a Zoho Desk organization. This step of associating the token and the organization, which happens in the backend while getting authorization consent from the end user, is called organization binding.

If the end-user has only one Zoho Desk organization (portal), the OAuth token is linked to it automatically. If they have multiple organizations, they must manually select the one with which the token must be linked, as illustrated in the following image.

After they click the Submit button, the OAuth token is generated with the organization information bound to it.

Zoho Desk APIs automatically extract organization information from OAuth tokens. Therefore, it is not necessary to add the extra orgId query parameter in an API call or pass it in the API's header. However, if you choose to do so, make sure that the value of orgId is same as that of the portal bound with the OAuth token. If the IDs do not match, the API call fails, and the OAUTH_ORG_MISMATCHerror message is returned.

Webhook

Zoho Desk supports webhooks that asynchronously deliver information on events that occur in the help desk. These events include actions, such as creating or updating a ticket, contact, or account, and so on. For information on how to include Zoho Desk webhooks in your service, refer to this document.

Phone Bridge

The Zoho PhoneBridge feature connects your PBX system and your Zoho Desk portal that holds all the important details of your customers. With this feature, Zoho Desk offers you a platform to manage incoming and outgoing calls on your computer. Additionally, you can view the name, phone number, and overall customer happiness score of your customers when they call. To know more about this please refer this document

Help Center

Your help center is one of the key channels through which customers can seek support. This portal provides your customers with access to major help modules, such as your knowledge base, user community, live chat, and ticket submission form. A well-designed and well-maintained help center ensures good self-service capabilities for your customers and lesser burden on your support agents. To know more about this please refer this document

Java SDK

The Zoho Desk Java SDK helps you create client Java applications that can be integrated with your Zoho Desk portal. This SDK makes it easy to access and use Zoho Desk APIs where necessary. In other words, it serves as a wrapper for the REST APIs, making it easy to use Zoho Desk's functionalities in your custom applications. To know more about this SDK please refer this document

Organizations

In Zoho Desk, each business is categorized as an organization. If you have multiple businesses, set each business up as an individual organization by creating a new signup and generating a unique organization ID. All APIs except the ones directly related to organizations must include the organization ID in the header in this format: orgId:{organization_id}

ATTRIBUTES

Attribute Name

Data Type

Description

companyName

string

Actual name of the organization/business

portalName

string

Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.

phoneNumber

string

Phone number of the organization

edition

string

Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, and PROFESSIONAL.

long

Unique ID of the organization

isDefault

boolean

Key that returns if the organization is the default organization of the user

isAdminInOrg

boolean

Key that returns if the user is an admin in the organization

portalURL

string

URL of the help desk portal

logoURL

string

URL of the image file displaying the organization's logo

alias

string

Alternative name for the help desk portal

employeeCount

string

Number of employees in the organization

description

string

Brief description of the organization

mobile

string

Mobile number of the organization

website

string

Website of the organization

fax

string

Fax number of the organization

primaryContact

string

Primary contact person in the organization

street

string

Street in which the organization's office is located

city

string

City in which the organization's office is located

state

string

State in which the organization's office is located

zip

string

Zip code of the organization's address

country

string

Country in which the organization's office is located

currencyLocale

string

Currency locale in which the organization operates

currencySymbol

string

Currency symbol used in the organization

Example

{ "zip" : "68838-2640", "country" : "United States", "website" : "www.zylker.com", "city" : "Bernierview", "companyName" : "Zylker INC.", "mobile" : "9848022338", "description" : "We are Zylker Support.", "edition" : "ENTERPRISE", "currencySymbol" : "$", "employeeCount" : "10", "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true, "isDefault" : "false", "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8", "phoneNumber" : "9884358081", "portalName" : "zylker", "street" : "70961 Powlowski Crossing", "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do", "primaryContact" : "steve@zylker.com", "currencyLocale" : "US", "alias" : "Zylker Teams", "id" : "3981311", "state" : "NC", "fax" : "8392839821" }

Get organization

This API fetches the details of an organization from your help desk.

Query Params

Param Name

Data Type

Description

includeCustomDomain

boolean

optional,
default : false

Key that denotes if the customDomain field must be included in the API response

GET /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311?includeCustomDomain=true
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

OrganizationAPI organization = ZDesk.getOrganizationAPIInstance(mailId);
GetOrganizationFilter filter = new GetOrganizationFilter.Builder().setIncludeCustomDomain(includeCustomDomain).build();
Organization response = organization.getOrganization( organizationId, filter );

Response Example

{
  "country" : "United States",
  "city" : "Bernierview",
  "companyName" : "Zylker INC.",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "isAdminInOrg" : true,
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "portalName" : "zylker",
  "street" : "70961 Powlowski Crossing",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "fax" : "8392839821",
  "zip" : "68838-2640",
  "website" : "www.zylker.com",
  "mobile" : "9848022338",
  "currencySymbol" : "$",
  "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
  "customDomain" : "support.zylker.com",
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
  "primaryContact" : "steve@zylker.com"
}

Get all organizations

This API lists all organizations to which the current user belongs.

GET /api/v1/organizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

OrganizationAPI organization = ZDesk.getOrganizationAPIInstance(mailId);
List<Organization> response = organization.getOrganizations( );

Response Example

{
  "data" : [ {
    "zip" : "68838-2640",
    "country" : "United States",
    "website" : "www.zylker.com",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "mobile" : "9848022338",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "currencySymbol" : "$",
    "employeeCount" : "10",
    "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
    "phoneNumber" : "9884358081",
    "portalName" : "zylker",
    "street" : "70961 Powlowski Crossing",
    "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
    "primaryContact" : "steve@zylker.com",
    "currencyLocale" : "US",
    "alias" : "Zylker Teams",
    "id" : "3981311",
    "state" : "NC",
    "fax" : "8392839821"
  }, {
    "zip" : "33560-8932",
    "country" : "United States",
    "website" : "www.nshlerin.com",
    "city" : "Port Cierra",
    "companyName" : "Nshlerin LLC.",
    "mobile" : "987654321",
    "description" : "We are Nshlerin Support.",
    "edition" : "PROFESSIONAL",
    "currencySymbol" : "$",
    "employeeCount" : "20",
    "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/5988319/favicon?no-cache=b31a9627de49fge046fcab71sf3359eq",
    "phoneNumber" : "9884309090",
    "portalName" : "nshlerin",
    "street" : "269 Adam Flats",
    "portalURL" : "http://support.nshlerin.com/support/nshlerin/ShowHomePage.do",
    "primaryContact" : "kelvin@nshlerin.com",
    "currencyLocale" : "US",
    "alias" : "Nshlerinians",
    "id" : "5988319",
    "state" : "Port Cierra",
    "fax" : "987654321"
  } ]
}

Get accessible organizations

This API lists all organizations which can be accessed using the current Oauth token.

GET /api/v1/accessibleOrganizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accessibleOrganizations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "zip" : "68838-2640",
    "country" : "United States",
    "website" : "www.zylker.com",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "mobile" : "9848022338",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "currencySymbol" : "$",
    "employeeCount" : "10",
    "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
    "phoneNumber" : "9884358081",
    "portalName" : "zylker",
    "street" : "70961 Powlowski Crossing",
    "portalURL" : "https://support.zylker.com/support/zylker/ShowHomePage.do",
    "primaryContact" : "steve@zylker.com",
    "currencyLocale" : "US",
    "alias" : "Zylker Teams",
    "id" : "3981311",
    "state" : "NC",
    "fax" : "8392839821"
  } ]
}

Update organization

This API updates the details of an organization.

Attributes

Param Name

Data Type

Description

companyName

string

optional,
max chars : 50

Actual name of the organization/business

portalName

string

optional,
max chars : 100

Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.

phoneNumber

string

optional,
max chars : 30

Phone number of the organization

edition

string

optional,
max chars : 100

Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, and PROFESSIONAL.

alias

string

optional,
max chars : 50

Alternative name for the help desk portal

employeeCount

string

optional,
max chars : 19

Number of employees in the organization

description

string

optional,
max chars : 250

Brief description of the organization

mobile

string

optional,
max chars : 30

Mobile number of the organization

website

string

optional,
max chars : 50

Website of the organization

fax

string

optional,
max chars : 100

Fax number of the organization

primaryContact

string

optional,
max chars : 100

Primary contact person in the organization

street

string

optional,
max chars : 50

Street in which the organization's office is located

city

string

optional,
max chars : 50

City in which the organization's office is located

state

string

optional,
max chars : 50

State in which the organization's office is located

zip

string

optional,
max chars : 100

Zip code of the organization's address

country

string

optional,
max chars : 50

Country in which the organization's office is located

currencyLocale

string

optional,
max chars : 100

Currency locale in which the organization operates

PATCH /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/organizations/3981311
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "portalName" : "zylkerdesk", "companyName" : "Zylker Desk", "primaryContact" : "kelvin@zylker.com", "mobile" : "9848022338", "employeeCount" : "10" }'

Response Example

{
  "zip" : "68838-2640",
  "country" : "United States",
  "website" : "www.zylker.com",
  "city" : "Bernierview",
  "companyName" : "Zylker Desk",
  "mobile" : "9848022338",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "currencySymbol" : "$",
  "employeeCount" : "10",
  "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
  "isAdminInOrg" : true,
  "isDefault" : "false",
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "phoneNumber" : "9884358081",
  "portalName" : "zylkerdesk",
  "street" : "70961 Powlowski Crossing",
  "portalURL" : "http://support.zylker.com/support/zylkerdesk/ShowHomePage.do",
  "primaryContact" : "kelvin@zylker.com",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "fax" : "8392839821"
}

Get organization logo

This API fetches the logo set for an organization/portal in your help desk.

Query Params

Param Name

Data Type

Description

no-cache

string

optional,
max chars : 100

Key that helps avoid browser cache. Only alphanumeric values are allowed.

fileSize

string

optional,
max chars : 100

Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.

GET /api/v1/organizations/{organization_Id}/logo

OAuth Scope

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311/logo
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get organization favicon

This API fetches the favicon set for an organization/portal in your help desk.

Query Params

Param Name

Data Type

Description

no-cache

string

optional,
max chars : 100

Key that helps avoid browser cache. Only alphanumeric values are allowed.

fileSize

string

optional,
max chars : 100

Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.

GET /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311/favicon
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Update organization logo

This API updates the logo set for an organization/portal in your help desk.

Note: To upload organization logo generate OAuthToken for the scope: Desk.settings.UPDATE,profile.orglogo.UPDATE or Desk.basic.UPDATE,profile.orglogo.UPDATE

File Params

logo

Content-Type:multipart/form-data

Image file of the logo.The maximum file size allowed is 2 MB.

POST /api/v1/organizations/{organization_Id}/logo

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/organizations/3981311/logo
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "companyLogoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6"
}

Update organization favicon

This API updates the favicon set for an organization/portal in your help desk.

File Params

favicon

Content-Type:multipart/form-data

Image file of the favicon.The maximum file size allowed is 2 MB.

POST /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/organizations/3981311/favicon
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "faviIconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=ffc59c3ba6585c12fb306f5174948ff6"
}

Delete organization logo

This API deletes the logo set for an organization/portal in your help desk.

DELETE /api/v1/organizations/{organization_Id}/logo

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/organizations/3981311/logo
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Delete organization favicon

This API updates the favicon set for an organization/portal in your help desk.

DELETE /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/organizations/3981311/favicon
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Update default organization

This API updates the default organization for the current user in Zoho Desk.

Attributes

Param Name

Data Type

Description

long

required

Unique ID of the organization to be marked as default org

POST /api/v1/organizations/markDefault

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/organizations/markDefault
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "id" : "3981311"
}'

Response Example

Agents

Agents are the customer service executives in your organization. They are the primary users of the helpdesk software, using which they interact with contacts and resolve tickets.

ATTRIBUTES

Attribute Name

Data Type

Description

emailId

string

Email ID of the agent

status

string

Activation status of the agent: ACTIVE or DISABLED

lastName

string

Last name of the agent

firstName

string

First name of the agent

name

string

Full name of the agent

phone

string

Phone number of the agent

mobile

string

Mobile number of the agent

extn

string

Extension number of the agent

associatedDepartmentIds

list

Departments with which the agent is associated

associatedChatDepartmentIds

list

Chat departments with which the agent is associated

long

ID of the agent

zuid

long

Zoho user ID of the agent

roleId

long

Role ID of the agent

profileId

long

Profile ID of the agent

photoURL

string

URL of the image file displaying the agent's photo

isConfirmed

boolean

Key that returns if the agent is a confirmed user in the portal or not

rolePermissionType

string

The Role Permission type of Agent

aboutInfo

string

Agent's about info

channelExpert

list

The channels handled for the Agent

countryCode

string

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

string

The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.

langCode

string

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

Example

{ "lastName" : "case", "extn" : "3298", "roleId" : "1892000000056099", "langCode" : "fr_FR", "mobile" : "", "timeZone" : "Pacific/Majuro", "emailId" : "case@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10687231", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ], "firstName" : "", "photoURL" : null, "phone" : "492-736-6424", "profileId" : "1892000000056091", "countryCode" : "en_US", "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ], "name" : "case", "rolePermissionType" : "Admin", "isConfirmed" : true, "aboutInfo" : "Expert in handling tickets and Automations", "id" : "1892000000056007", "status" : "ACTIVE" }

Get agent

This API fetches details of an agent in your help desk.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, and associatedChatDepartments. You can include all four values by separating them with commas in the API request.

GET /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/1892000000056096?include=profile,role,associatedDepartments,associatedChatDepartments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
Agent response = agent.getAgent( agentId, include );

Response Example

{
  "associatedChatDepartments" : [ {
    "name" : "Developement",
    "id" : "1892000000006907"
  } ],
  "lastName" : "case",
  "extn" : "3298",
  "role" : {
    "name" : "CEO",
    "id" : "1892000000056099"
  },
  "langCode" : "fr_FR",
  "emailId" : "case@zylker.com",
  "photoURL" : null,
  "countryCode" : "en_US",
  "isConfirmed" : true,
  "id" : "1892000000056096",
  "roleId" : "1892000000056099",
  "profile" : {
    "name" : "Administrator",
    "id" : "1892000000056091"
  },
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "associatedChatDepartmentIds" : [ "1892000000006907" ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "associatedDepartments" : [ {
    "name" : "Developement",
    "id" : "1892000000006907"
  }, {
    "name" : "R & D",
    "id" : "1892000000082069"
  } ],
  "firstName" : "",
  "phone" : "492-736-6424",
  "profileId" : "1892000000056091",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "case",
  "rolePermissionType" : "Admin",
  "aboutInfo" : "Expert in handling tickets and Automations",
  "status" : "ACTIVE"
}

List agents

This API lists a particular number of agents, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the agents must be fetched

limit

integer

optional,
range : 0-200

Number of agents to fetch. The default value is 10 and the maximum value supported is 200.

status

string

optional,
max chars : 100

Key that filters agents based on their activation status: ACTIVE or DISABLED

departmentIds
see documentation

long

optional

Comma-separated array of department IDs. Maximum number of IDs allowed is 50.

profileIds
see documentation

long

optional

Comma-separated array of profile IDs. Maximum number of IDs allowed is 50.

roleIds
see documentation

long

optional

Comma-separated array of role IDs. Maximum number of IDs allowed is 50.

rolePermissionType

string

optional,
max chars : 100

Types of roles and permissions of the agents to list. Values allowed are AgentPublic, AgentPersonal,AgentTeamPersonal, Admin, Light, Custom, and ${NON_LIGHT}. ${NON_LIGHT} refers to agents who are not associated with the light agent profile.

isConfirmed

boolean

optional

Key that denotes if the agents must be confirmed or unconfirmed.

isLightAgent

boolean

optional

Key that denotes if the agents must be light or non light.

include
see documentation

string

optional,
max chars : 100

Secondary information related to agents, Values allowed are profile, role. You can include all two values by separating them with commas in the API request.

searchStr

string

optional,
max chars : 100

String to search for agents by first name, last name, or email ID. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for agents whose first name, last name, or email ID start with the string, 2) *string* - Searches for agents whose first name, last name, or email ID contain the string, 3) string - Searches for agents whose first name, last name, or email ID is an exact match for the string

fieldName

string

optional,
max chars : 100

Name of the field that must be used for searching and listing agents. Values allowed are: firstName, lastName, name, and emailId

sortOrder

string

optional,
max chars : 100

To sort the available list of agents in either ascending or descending order. Values allowed are: asc or desc

GET /api/v1/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
GetAgentsFilter filter = new GetAgentsFilter.Builder().setFieldName(fieldName).build();
List<Agent> response = agent.getAgents( from, limit, include, filter );

Response Example

{
  "data" : [ {
    "lastName" : "case",
    "extn" : "3298",
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "case@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "zyl",
    "photoURL" : null,
    "phone" : "492-736-6424",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "zyl case",
    "rolePermissionType" : "Admin",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "jade",
    "extn" : "3203",
    "roleId" : "1892000000056899",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "jade@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10657727",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ],
    "firstName" : "",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3981311",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web" ],
    "name" : "jade",
    "rolePermissionType" : "Light",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tasks",
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "john",
    "extn" : "3228",
    "roleId" : "1892000000056004",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "john@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10713988",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "68779989",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Chat", "Phone", "Twitter", "Web", "Email" ],
    "name" : "john",
    "rolePermissionType" : "AgentPersonal",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling Workflows and Agents",
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "Waugh",
    "extn" : "4020",
    "roleId" : "1892000000056004",
    "langCode" : "ja_JP",
    "mobile" : "",
    "timeZone" : "Asia/Tokyo",
    "emailId" : "stephen@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : null,
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "Steve",
    "photoURL" : null,
    "phone" : "",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ ],
    "name" : "Steve Waugh",
    "rolePermissionType" : "Custom",
    "isConfirmed" : false,
    "aboutInfo" : "Expert in handling Knowledge base and comunity ",
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get agents count

This API lists the agents count by status, confirmed and include light

Query Params

Param Name

Data Type

Description

status

string

optional,
max chars : 100

Parameter that filters agents based on their activation status: ACTIVE or DISABLED

isConfirmed

boolean

optional

Filters Confirmed & Unconfirmed agents

includeLightAgent

boolean

optional

Count light agent.

GET /api/v1/agents/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/count
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get agent details by agentId

This API fetches details of agents via the agent IDs passed in the API request.

Query Params

Param Name

Data Type

Description

agentIds

long

required

Comma-separated array of agent IDs. Maximum number of IDs allowed is 50.

GET /api/v1/agentsByIds?agentIds={agent_ids}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agentsByIds?agentIds=1892000000056007,1892000000042001,1892000000888059
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
List<Agent> response = agent.getAgentsByIds(agentIds );

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "case",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "case@zylker.com",
    "id" : "1892000000056007",
    "zuid" : "437793"
  }, {
    "firstName" : "",
    "lastName" : "jade",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3981311",
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "jade@zylker.com",
    "id" : "1892000000042001",
    "zuid" : "279392"
  }, {
    "firstName" : "Steve",
    "lastName" : "Waugh",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000888059/photo?orgId=3981311",
    "roleId" : "70000000127346",
    "profileId" : "70000000120834",
    "emailId" : "stephen@zylker.com",
    "id" : "1892000000888059",
    "zuid" : "91723912"
  } ]
}

Get My Information

This API fetches details of the currently logged in agent.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, and associatedChatDepartments. You can pass multiple values by separating them with commas in the query param

GET /api/v1/myinfo

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myinfo?include=profile,role,associatedDepartments,associatedChatDepartments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
Agent response = agent.getMyInfo( include );

Response Example

{
  "associatedChatDepartments" : [ {
    "sanitizedName" : "Developement",
    "name" : "Developement",
    "id" : "1892000000006907"
  } ],
  "lastName" : "Emard",
  "extn" : "",
  "role" : {
    "name" : "CEO",
    "id" : "1892000000056099"
  },
  "langCode" : "fr_FR",
  "emailId" : "emardtorrey@zylker.com",
  "photoURL" : null,
  "countryCode" : "en_US",
  "isConfirmed" : true,
  "id" : "1892000000056007",
  "roleId" : "1892000000056099",
  "profile" : {
    "name" : "Administrator",
    "id" : "1892000000056091"
  },
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "associatedChatDepartmentIds" : [ "1892000000006907" ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "associatedDepartments" : [ {
    "sanitizedName" : "Developement",
    "name" : "Developement",
    "id" : "1892000000006907"
  }, {
    "sanitizedName" : "r-d",
    "name" : "R & D",
    "id" : "1892000000082069"
  } ],
  "firstName" : "Torrey",
  "phone" : "",
  "profileId" : "1892000000056091",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "Torrey Emard",
  "rolePermissionType" : "Admin",
  "aboutInfo" : "Expert in handling tickets and Automations",
  "status" : "ACTIVE"
}

Activate agents

This API activates agents in your help desk.

Note: To activate agents in CRMPlus and ZohoOne, first generate an authtoken through this URL: https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoDirectory/directoryapi

Attributes

Param Name

Data Type

Description

agentIds

list

required

Ids of Agents

POST /api/v1/agents/activate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/activate
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

Deactivate agent

This API deactivates an agent in your help desk.

POST /api/v1/agents/{agent_id}/deactivate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/deactivate
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Reinvite unconfirmed agents

This API sends reinvitation mails to unconfirmed agents.

Attributes

Param Name

Data Type

Description

agentIds

list

required

Ids of Agents

POST /api/v1/agents/reinvite

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/reinvite
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

Add agent

This API adds an agent to your help desk.

Keep in mind the following points while adding an agent:

The emailId, lastName, associatedDepartmentIds, and rolePermissionType are mandatory in the API request.
To assign the profile and role for the agents, pass any of the following values with the rolePermissionType key:
1. For the Support Administrator profile and CEO role, pass "rolePermissionType":"Admin"
2. For the Agent profile and public role, pass "rolePermissionType":"AgentPublic"
3. For the Agent profile and personal role, pass "rolePermissionType":"AgentPersonal"
4. For custom profiles and roles, pass "rolePermissionType":"Custom" and "roleId":"<actual role ID>", "profileId":"<actual profile ID>"
5. For the light agent profile and role, pass "rolePermissionType":"Light"
6. For the Agent profile and Personal Team role, pass "rolePermissionType":"AgentTeamPersonal"

Attributes

Param Name

Data Type

Description

emailId

string

required,
max chars : 100

Email ID of the agent

lastName

string

required,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

required

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

required,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 150

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

string

optional,
max chars : 100

The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.

langCode

string

optional,
max chars : 100

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

POST /api/v1/agents

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "lastName" : "Walsh", "firstName" : "Marisol", "countryCode" : "en_US", "langCode" : "fr_FR", "rolePermissionType" : "Admin", "emailId" : "marisol51@zylker.com", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ] }'

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
Agent agentObj = new Agent();
agentObj.setLastName(lastName);
agentObj.setExtn(extn);
agentObj.setLangCode(langCode);
agentObj.setMobile(mobile);
agentObj.setEmailId(emailId);
agentObj.setFirstName(firstName);
Agent response = agent.addAgent( agentObj );

Response Example

{
  "lastName" : "Walsh",
  "extn" : "",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "marisol51@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "firstName" : "Marisol",
  "photoURL" : null,
  "phone" : "",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ ],
  "name" : "Walsh Marisol",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Update agent

This API updates details of an agent.

Note: To update details of agents in CRMPlus and ZohoOne, first generate an authtoken through this URL: https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoDirectory/directoryapi

Attributes

Param Name

Data Type

Description

emailId

string

optional,
max chars : 100

Email ID of the agent

lastName

string

optional,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

optional

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

optional,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 150

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

string

optional,
max chars : 100

The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.

langCode

string

optional,
max chars : 100

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

PATCH /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/agents/1892000000056007
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "lastName" : "Marisol Walsh", "firstName" : "K", "phone" : "764-484-8068", "rolePermissionType" : "Light", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ] }'

Response Example

{
  "lastName" : "Marisol Walsh",
  "extn" : "3298",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "marisol51@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "firstName" : "K",
  "photoURL" : null,
  "phone" : "764-484-8068",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ "Facebook", "Email", "Forums" ],
  "name" : "K Marisol Walsh",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "Expert in handling Reports",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Delete unconfirmed agents

This API deletes unconfirmed agents from your help desk.

Attributes

Param Name

Data Type

Description

agentIds

list

required

Ids of Agents

POST /api/v1/agents/deleteUnconfirmed

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/deleteUnconfirmed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

Delete confirmed agent

This API deletes a confirmed agent from your help desk.

Attributes

Param Name

Data Type

Description

anonymizedName

string

optional,
max chars : 50

Nickname of the agent, which will appear on their entity history page

isAnonymize

boolean

optional

Key that determines if the deleted agent must be anonymized in the help desk

POST /api/v1/agents/{agent_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/delete
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "anonymizedName" : "Anonyme",
  "isAnonymize" : true
}'

Response Example

Anonymize deleted agent

This API removes the identification details of a deleted agent.

Attributes

Param Name

Data Type

Description

anonymizedName

string

optional,
max chars : 50

Nickname of the agent, which will appear on their entity history page

POST /api/v1/deletedAgents/{agent_id}/anonymize

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/deletedAgents/19000001075071/anonymize
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "anonymizedName" : "Anonyme"
}'

Response Example

Upload my photo

This API sets the profile photo for the currently logged in agent.

Note: To upload your photo generate OAuthToken for the scope: Desk.settings.UPDATE,profile.userphoto.UPDATE or Desk.basic.UPDATE,profile.userphoto.UPDATE

File Params

userPhoto

Content-Type:multipart/form-data

Image file containing the agent's photo. Maximum file size allowed is 500KB; maximum file limit is one; and extensions allowed are: .jpg, .png, .gif, and .jpeg.

POST /api/v1/uploadMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/uploadMyPhoto
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=3981311"
}

Get agent photo

This API gets the profile photo for the given agent id.

Note: To get agent photo generate OAuthToken for the scope: Desk.settings.READ,profile.userphoto.READ or Desk.basic.READ,profile.userphoto.READ

Query Params

Param Name

Data Type

Description

fileSize

string

optional,
max chars : 100

Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.

GET /api/v1/agents/{agent_id}/photo?orgId={org_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=3981311&fileSize=THUMBNAIL
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Delete My Photo

This API deletes the profile photo of the currently logged in agent.

POST /api/v1/deleteMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/deleteMyPhoto
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get My Preferences

This API fetches the preferences of the currently logged in agent.

GET /api/v1/myPreferences

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myPreferences
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "namePattern" : [ "FIRST_NAME", "LAST_NAME" ],
  "articleAutoSuggestion" : "ENABLED",
  "keyBoardShortcuts" : "ENABLED",
  "pinAllAccounts" : "ENABLED",
  "collapseSidePanel" : "DISABLED",
  "pinAllTickets" : "ENABLED",
  "ticketConversationView" : "ENABLED",
  "contactsView" : "LIST",
  "accountsView" : "LIST",
  "pinAllContacts" : "ENABLED",
  "ticketsView" : "DUEDATE_QUEUE",
  "datePattern" : "dd/MM/yyyy",
  "defaultSendBehavior" : "Send",
  "currentDepartment" : "allDepartment",
  "timeFormat" : "12-hour",
  "loginLandingPage" : "LISTVIEW",
  "loadGettingStartedPage" : "DISABLED"
}

Update My Preferences

This API updates the preferences of the currently logged in agent.

Attributes

Param Name

Data Type

Description

namePattern

List

optional

Pattern that defines how the names should be displayed

currentDepartment

long

optional

A valid active departmentId to which the agent is associated | 'allDepartment'

PATCH /api/v1/myPreferences

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/myPreferences
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "namePattern" : [ "LAST_NAME", "FIRST_NAME" ], "articleAutoSuggestion" : "ENABLED", "keyBoardShortcuts" : "ENABLED", "pinAllAccounts" : "ENABLED", "collapseSidePanel" : "DISABLED", "pinAllTickets" : "ENABLED", "ticketConversationView" : "ENABLED", "contactsView" : "LIST", "accountsView" : "LIST", "pinAllContacts" : "ENABLED", "ticketsView" : "STATUS_QUEUE", "defaultSendBehavior" : "Send", "datePattern" : "dd/MM/yyyy", "currentDepartment" : "1892000000082069", "timeFormat" : "12-hour", "loginLandingPage" : "LISTVIEW", "loadGettingStartedPage" : "DISABLED" }'

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
boolean response = agent.updateMyPreferences( namePattern, currentDepartment );

Response Example

Schedule reassignment for deactivated or deleted agents

This API schedules reassignment of tickets, tasks, and automations belonging to a deleted/deactivated agent to another agent within the same department.

Attributes

Param Name

Data Type

Description

agentReassignment

list

required

Details of agents to whom the resources associated with the agent will be reassigned

POST /api/v1/agents/{agent_id}/reassignment

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/reassignment
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "agentReassignment" : [ { "departmentId" : 19000000012754, "taskNewOwner" : "19000000008734", "ticketNewOwner" : "19000000142005" }, { "departmentId" : 19000000010674, "taskNewOwner" : "19000000008872", "ticketNewOwner" : "19000000182001" }, { "departmentId" : 19000000007073, "taskNewOwner" : "19000000008872", "ticketNewOwner" : "19000000182001" } ] }'

Response Example

Profiles

Profiles control the user permissions to access help desk modules, records, fields in a record, and other utilities, such as import, export, send email, etc. Users associated with a profile can access only the functions that are assigned to that profile.

ATTRIBUTES

Attribute Name

Data Type

Description

name

string

Name of the profile

description

string

Description of the profile

isVisible

boolean

If the profile is visible in UI

type

string

Type of the profile. Possible values are Administrator, Standard, Light, Portal, and Custom

default

boolean

If the profile is system generated

long

Id of the profile

permissions

show Attributes

object

Details of the permissions for the profile

timeEntry

show Attributes

object

Permission details for the module

accounts

show Attributes

object

Permission details for the module

contracts

show Attributes

object

Permission details for the module

tasks

show Attributes

object

Permission details for the module

kbCategory

show Attributes

object

Permission details for the module

contacts

show Attributes

object

Permission details for the module

reports

show Attributes

object

Permission details for the module

products

show Attributes

object

Permission details for the module

tickets

show Attributes

object

Permission details for the module

chat

object

Permission details for the module

community

object

Permission details for the module

social

object

Permission details for the module

agents

object

Permission details for the module

setup

show Attributes

object

Permission details for settings

comments

show Attributes

object

Permission details for comments

crmInteg

show Attributes

object

Permission details for CRM integration

calls

show Attributes

object

Permission details for the module

events

show Attributes

object

Permission details for the module

financeInteg

show Attributes

object

Permission details for Zoho Finance integration

show Attributes

object

Permission details for the IM module

show Attributes

object

Permission details for GC

Example

{ "default" : true, "permissions" : { "crmInteg" : { "crmContactsActivityEvents" : false, "crmAccountsActivityEvents" : false, "crmAccountsActivityTasks" : false, "crmAccountsInfo" : false, "crmContactsActivityCalls" : false, "crmAccountsNotes" : false, "crmAccountsActivityCalls" : false, "crmContactsInfo" : false, "crmContactsNotes" : false, "crmContactsActivityTasks" : false, "crmAccountsPotentials" : false, "crmContactsPotentials" : false }, "reports" : { "view" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "tickets" : { "mergeTickets" : true, "changeOwner" : true, "import" : true, "handleUnassigned" : true, "edit" : true, "closeTicket" : true, "mailReview" : true, "delete" : true, "view" : true, "create" : true, "addFollowers" : true, "export" : true, "mailSend" : true, "unassignedChangeOwner" : false, "shareTickets" : true }, "comments" : { "edit" : true, "delete" : true }, "social" : { "view" : true }, "contracts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "community" : { "view" : true }, "products" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "agents" : { "overview" : true, "edit" : false, "create" : true, "delete" : true, "viewAllFields" : true }, "kbCategory" : { "view" : true, "editAllArticles" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "setup" : { "timeTracking" : true, "fetchAcrossDepartment" : true, "globalReports" : true, "exportPortalUsers" : true, "layouts" : true, "automation" : true, "featureConfig" : true, "customerHappiness" : true, "department" : true, "portal" : true, "webForm" : true, "rebranding" : true, "email" : true, "tabsAndFields" : true, "exportUsers" : true, "teams" : true, "social" : true, "templates" : true, "moveRecords" : true, "permission" : true, "signUpApproval" : true, "community" : true, "importHistory" : true, "manageAgents" : true, "portalUsers" : true, "managerDashboard" : true, "googleAnalytics" : true, "chat" : true, "telephony" : true }, "financeInteg" : { "sendInvoice" : false, "createEstimate" : false, "createContact" : false, "viewInvoice" : false, "createInvoice" : false, "sendEstimate" : false, "viewEstimate" : false }, "accounts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "timeEntry" : { "view" : true, "edit" : true, "create" : true, "delete" : true }, "contacts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "tasks" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true } }, "name" : "Support Administrator", "description" : "Set the privileges for support administrators.", "id" : "5000000015288", "isVisible" : true, "type" : "Administrator" }

List profiles

This API lists a particular number of user profiles, based on the limit specified.

Query Params

Param Name

Data Type

Description

visible

boolean

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

Key that denotes whether the profiles must be default profiles or custom profiles

searchStr

string

optional,
max chars : 100

String to search for profile by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for profiles whose name or description start with the string, 2) *string* - Searches for profiles whose name or description contain the string, 3) string - Searches for profiles whose name or description is an exact match for the string

GET /api/v1/profiles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/profiles?visible=true
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
List<Profile> response = profile.getProfiles(default, visible, searchStr );

Response Example

{
  "data" : [ {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : true
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : true,
        "fetchAcrossDepartment" : true,
        "globalReports" : true,
        "exportPortalUsers" : true,
        "layouts" : true,
        "automation" : true,
        "featureConfig" : true,
        "customerHappiness" : true,
        "department" : true,
        "portal" : true,
        "webForm" : true,
        "rebranding" : true,
        "email" : true,
        "tabsAndFields" : true,
        "exportUsers" : true,
        "teams" : true,
        "social" : true,
        "templates" : true,
        "moveRecords" : true,
        "permission" : true,
        "signUpApproval" : true,
        "community" : true,
        "importHistory" : true,
        "manageAgents" : true,
        "portalUsers" : true,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : true,
        "telephony" : true
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Support Administrator",
    "description" : "Set the privileges for support administrators.",
    "id" : "5000000015288",
    "isVisible" : true,
    "type" : "Administrator"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : false,
        "import" : false,
        "handleUnassigned" : false,
        "edit" : false,
        "closeTicket" : false,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : false,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "community" : {
        "view" : false
      },
      "products" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : false,
        "create" : false,
        "delete" : false
      },
      "contacts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      }
    },
    "name" : "Light Agent",
    "description" : "Set the privilege for light agents",
    "id" : "5000000015306",
    "isVisible" : true,
    "type" : "Light"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : true,
        "import" : false,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : false,
        "mailReview" : false,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : false,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "tasks" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      }
    },
    "name" : "Newbie Agent",
    "description" : "Set the privileges for new agents.",
    "id" : "5000000015303",
    "isVisible" : true,
    "type" : "Custom"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : false,
        "import" : false,
        "handleUnassigned" : false,
        "edit" : false,
        "closeTicket" : false,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : false
      },
      "contracts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "community" : {
        "view" : false
      },
      "products" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "timeEntry" : {
        "view" : false,
        "edit" : false,
        "create" : false,
        "delete" : false
      },
      "contacts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "tasks" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      }
    },
    "name" : "Help Center",
    "description" : "This profile will have the permissions of End Users",
    "id" : "5000000015294",
    "isVisible" : false,
    "type" : "Portal"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Agent",
    "description" : "Set the privileges for standard agents",
    "id" : "5000000015291",
    "isVisible" : true,
    "type" : "Standard"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Supervisor",
    "description" : "Set the privileges for supervisory users.",
    "id" : "5000000015297",
    "isVisible" : true,
    "type" : "Custom"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : true,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : false,
        "telephony" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Support Manager",
    "description" : "Set the privileges for managerial users.",
    "id" : "5000000015300",
    "isVisible" : true,
    "type" : "Custom"
  } ]
}

Get profile count

This API fetches the number of profiles configured in your help desk.

Query Params

Param Name

Data Type

Description

visible

boolean

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

Key that denotes whether the profiles must be default profiles or custom profiles

GET /api/v1/profiles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/profiles/count?visible=true
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 8
}

Get profile

This API fetches the details of a particular profile.

GET /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/profiles/4000000008464
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile response = profile.getProfile( profileId );

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "4000000008464",
  "isVisible" : true,
  "type" : "Administrator"
}

Clone profile

This API replicates an existing profile.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 50

Name of the profile to be created

description

String

optional

Description of the profile to be created

POST /api/v1/profiles/{profile_id}/clone

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/profiles/4000000008543/clone
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Admin Advisors", "description" : "Advisors from management to assist the Support Administrators." }'

Response Example

{
  "default" : false,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Admin Advisors",
  "description" : "Advisors from management to assist the Support Administrators.",
  "id" : "5000000046001",
  "isVisible" : true,
  "type" : "Custom"
}

Update profile

This API updates the details of an existing profile.

Attributes

Param Name

Data Type

Description

name

string

optional,
max chars : 50

Name of the profile

description

string

optional,
max chars : 3200

Description of the profile

permissions

show Attributes

object

optional

Details of the permissions for the profile

timeEntry

show Attributes

object

optional

Permission details for the module

accounts

show Attributes

object

optional

Permission details for the module

contracts

show Attributes

object

optional

Permission details for the module

tasks

show Attributes

object

optional

Permission details for the module

kbCategory

show Attributes

object

optional

Permission details for the module

contacts

show Attributes

object

optional

Permission details for the module

reports

show Attributes

object

optional

Permission details for the module

products

show Attributes

object

optional

Permission details for the module

tickets

show Attributes

object

optional

Permission details for the module

chat

show Attributes

object

optional

Permission details for the module

community

show Attributes

object

optional

Permission details for the module

social

show Attributes

object

optional

Permission details for the module

agents

show Attributes

object

optional

Permission details for the module

setup

show Attributes

object

optional

Permission details for settings

comments

show Attributes

object

optional

Permission details for comments

crmInteg

show Attributes

object

optional

Permission details for CRM integration

calls

show Attributes

object

optional

Permission details for the module

events

show Attributes

object

optional

Permission details for the module

financeInteg

show Attributes

object

optional

Permission details for Zoho Finance integration

show Attributes

object

optional

Permission details for the IM module

show Attributes

object

optional

Permission details for GC

PATCH /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/profiles/4000000018001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "permissions" : { "reports" : { "view" : true, "edit" : true, "create" : false, "delete" : false, "export" : false } }, "name" : "Agent Advisors", "description" : "Advisors from CRM to assist the Support Agents." }'

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile profileObj = new Profile();
profileObj.setName(name);
profileObj.setDescription(description);
Profile response = profile.updateProfile( profileId, profileObj );

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : false,
      "delete" : false,
      "export" : false
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Agent Advisors",
  "description" : "Advisors from CRM to assist the Support Agents.",
  "id" : "4000000018001",
  "isVisible" : true,
  "type" : "Custom"
}

Delete profile

This API deletes a profile from your help desk.

Attributes

Param Name

Data Type

Description

transferToProfileId

long

required

The profile id to which the agents in the delete profile to be transferred to

POST /api/v1/profiles/{profile_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/profiles/4000000018001/delete
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "transferToProfileId" : "4000000008454"
}'

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
boolean response = profile.deleteProfile( profileId, transferToProfileId );

Response Example

Get my profile details

This API fetches the configuration details and permissions defined for the profile of the currently logged in user.

GET /api/v1/myProfile

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myProfile
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "35483000000008343",
  "isVisible" : true,
  "type" : "Administrator"
}

Get my profile permissions

This API fetches the permissions associated with the profile of the currently logged in user.

GET /api/v1/myProfilePermissions

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myProfilePermissions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile response = profile.getMyProfilePermissions( );

Response Example

{
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  }
}

List agents by profile

This API lists agents mapped to a particular profile.

Query Params

Param Name

Data Type

Description

active

boolean

optional

Activation status of the agents to list

confirmed

boolean

optional

Confirmation status of the agents to list

GET /api/v1/profiles/{profile_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/profiles/6000000011303/agents?active=true
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
GetAgentsByProfileFilter filter = new GetAgentsByProfileFilter.Builder().setActive(active).build();
List<Agent> response = profile.getAgentsByProfile( profileId, filter );

Response Example

{
  "agents" : [ {
    "firstName" : "",
    "lastName" : "John",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=437793",
    "roleId" : "7000000012324",
    "profileId" : "6000000011303",
    "emailId" : "john@zylker.com",
    "id" : "7000000013328",
    "zuid" : "437793"
  }, {
    "firstName" : "Steve",
    "lastName" : "Kyle",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "6000000011303",
    "emailId" : "kyle@zylker.com",
    "id" : "7000000012958",
    "zuid" : "5625416"
  } ]
}

Get light agent profile

This API fetches the different permissions configured for the light agent profile.

GET /api/v1/lightAgentProfile

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/lightAgentProfile
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : false,
      "changeOwner" : false,
      "import" : false,
      "handleUnassigned" : false,
      "edit" : false,
      "closeTicket" : false,
      "mailReview" : false,
      "delete" : false,
      "view" : true,
      "create" : false,
      "addFollowers" : false,
      "export" : true,
      "mailSend" : false,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : false,
      "delete" : false
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "community" : {
      "view" : false
    },
    "products" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : false,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : false,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : false,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : false,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : false,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false
    },
    "contacts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    }
  },
  "name" : "Light Agent",
  "description" : "Set the privilege for light agents",
  "id" : "15000000012421",
  "isVisible" : true,
  "type" : "Light"
}

Roles

Role refers to the user role that can be defined in Zoho Desk. Roles help define organization-wide hierarchy. Users at a higher hierarchy can always access all the records of at a lower hierarchy. For example, a Support Manager can access all the Agents' records, whereas Agents can access only their records.

ATTRIBUTES

Attribute Name

Data Type

Description

name

string

Name of the role

description

string

A short description of the role

isVisible

boolean

Key that denotes if the role is visible in the UI

isDefault

boolean

Key that denotes if the role is the default role

shareDataWithPeers

boolean

Key that denotes if the role shares data with its peer roles

long

ID of the role

reportsTo

long

ID of the role to which the current role reports

immediateSubRoles

list

IDs of roles that directly report to the current role

Example

{ "isDefault" : true, "shareDataWithPeers" : true, "immediateSubRoles" : [ "5000000054103", "5000000008813", "5000000057018" ], "name" : "CEO", "description" : "Agent belongs to this role can access all other user's data.", "reportsTo" : null, "id" : "5000000008807", "isVisible" : true }

List roles

This API lists a particular number of roles, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the roles must be listed

limit

integer

optional,
range : 0-500

Number of roles to display. The default value is 15 and the maximum value allowed is 500.

isVisible

boolean

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

Key that denotes whether the roles must be default roles or custom roles

searchStr

string

optional,
max chars : 100

String to search for roles by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for roles whose name or description start with the string, 2) *string* - Searches for roles whose name or description contain the string, 3) string - Searches for roles whose name or description is an exact match for the string

GET /api/v1/roles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/roles
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
GetRolesFilter filter = new GetRolesFilter.Builder().setIsDefault(isDefault).build();
List<Role> response = role.getRoles( from, limit, filter );

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "shareDataWithPeers" : true,
    "immediateSubRoles" : [ "50000785582324", "50000000779019", "50000001319909" ],
    "name" : "CEO",
    "description" : "Agent belongs to this role can access all other user's data.",
    "reportsTo" : null,
    "id" : "50000000008337",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ "50000091844659" ],
    "name" : "Manager",
    "description" : "Agents belongs to this cannot see admin role users data",
    "reportsTo" : "50000000008337",
    "id" : "50000000008339",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "PortalUser",
    "description" : "User belongs to this role are portal users they can access their cases and solutions only",
    "reportsTo" : "50000000008337",
    "id" : "50000000008341",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Development Team Member",
    "description" : "Development team members from Engineering",
    "reportsTo" : "50000000008337",
    "id" : "50000000469017",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Product Team Member",
    "description" : "Products Managers",
    "reportsTo" : "50000000008337",
    "id" : "50000000551386",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : true,
    "immediateSubRoles" : [ ],
    "name" : "Sales Team Member",
    "description" : "",
    "reportsTo" : "50000000008337",
    "id" : "50000000779019",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Personal",
    "description" : "Agents belongs to this role can see only unassigned and his/her data",
    "reportsTo" : null,
    "id" : "50000002634005",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Marketing Team Member",
    "description" : "",
    "reportsTo" : "50000000008337",
    "id" : "50000009610999",
    "isVisible" : true
  }, {
    "isDefault" : true,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "LightAgent",
    "description" : "Agents belonging to this role can access all user's data.",
    "reportsTo" : null,
    "id" : "50000565365005",
    "isVisible" : false
  } ]
}

List agents by role

This API lists agents mapped to a particular role.

GET /api/v1/roles/{role_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/roles/50000000008446/agents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Map<String, Object> response = role.getAgentsByRole( roleId );

Response Example

{
  "associatedAgents" : [ "50000000009163", "50000000009300", "50000000010007", "50000000010011", "50000000062391", "50000000062393" ]
}

Create role

This API creates a role in your help desk.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

required

Key that denotes if the role shares data with its peer roles

reportsTo

long

optional

ID of the role to which the current role reports

POST /api/v1/roles

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/roles
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "shareDataWithPeers" : true, "name" : "Customer Care Associate", "description" : "Can work on own tickets and can not re-assign tickets.", "reportsTo" : 5000000008807 }'

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role roleObj = new Role();
roleObj.setName(name);
roleObj.setDescription(description);
Role response = role.createRole( roleObj );

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : true,
  "immediateSubRoles" : [ ],
  "name" : "Customer Care Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807,
  "id" : "5000000002973",
  "isVisible" : true
}

Update role

This API updates details of an existing role.

Attributes

Param Name

Data Type

Description

name

string

optional,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

optional

Key that denotes if the role shares data with its peer roles

reportsTo

long

optional

ID of the role to which the current role reports

PATCH /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/roles/5000000002973
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "shareDataWithPeers" : true, "name" : "Customer Care and Sales Associate", "description" : "Can work on own tickets and can not re-assign tickets.", "reportsTo" : 5000000008807 }'

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role roleObj = new Role();
roleObj.setName(name);
roleObj.setDescription(description);
Role response = role.updateRole( roleId, roleObj );

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : true,
  "immediateSubRoles" : [ ],
  "name" : "Customer Care and Sales Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807,
  "id" : "5000000002973",
  "isVisible" : true
}

Delete role

This API deletes a role from your help desk.

Attributes

Param Name

Data Type

Description

transferToRoleId

long

required

Transfer the child-roles to the given role

POST /api/v1/roles/{role_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/roles/5000000002973/delete
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "transferToRoleId" : "5000000008807"
}'

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
boolean response = role.deleteRole( roleId, transferToRoleId );

Response Example

Get role

This API fetches the details of a particular role.

GET /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/roles/4000000012414
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role response = role.getRole( roleId );

Response Example

{
  "isDefault" : true,
  "shareDataWithPeers" : false,
  "immediateSubRoles" : [ "4000000012420", "4000000012417" ],
  "name" : "CEO",
  "description" : "Agent belongs to this role can access all other user's data.",
  "reportsTo" : null,
  "id" : "4000000012414",
  "isVisible" : true
}

Get role count

This API fetches the number of roles configured in your help desk.

Query Params

Param Name

Data Type

Description

isVisible

boolean

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

Key that denotes whether the roles must be default roles or custom roles

GET /api/v1/roles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/roles/count
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get personal role

This API fetches the details of the personal role configured in your help desk. Agents with personal role can view only the tickets assigned to them and unassigned tickets.

GET /api/v1/personalRole

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/personalRole
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : false,
  "immediateSubRoles" : [ ],
  "name" : "Personal",
  "description" : "Agents belongs to this role can see only unassigned and his/her data",
  "reportsTo" : null,
  "id" : "4000000012423",
  "isVisible" : false
}

List roles by role IDs

This API lists details of the roles whose IDs are passed in the API request.

Query Params

Param Name

Data Type

Description

roleIds
see documentation

long

required

Comma separated role ids. Maximum allowed count is 50

GET /api/v1/rolesByIds

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/rolesByIds?roleIds=4000000012423,4000000012420,4000000012414
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
List<Role> response = role.getRolesByIds(roleIds );

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ "4000000012420", "4000000012417" ],
    "name" : "CEO",
    "description" : "Agent belongs to this role can access all other user's data.",
    "reportsTo" : null,
    "id" : "4000000012414",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "PortalUser",
    "description" : "User belongs to this role are portal users they can access their cases and solutions only",
    "reportsTo" : "4000000012414",
    "id" : "4000000012420",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Personal",
    "description" : "Agents belongs to this role can see only unassigned and his/her data",
    "reportsTo" : null,
    "id" : "4000000012423",
    "isVisible" : false
  } ]
}

Teams

A team is a group of agents/users in a department. Just like how you can assign tickets or tasks to agents, you can also assign tickets and tasks to teams.

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the team

description

String

A short description of the team

departmentId

Long

ID of the department to which the team belongs

subTeams

list

List of sub-teams within the team

roles

list

List of roles to add to the team

rolesWithSubordinates

list

List of roles with subordinates to add to the team

agents

show Attributes

list

List of agents to add to the team

derivedAgents

list

List of agents derived with the properties set for the team

Example

{ "rolesWithSubordinates" : [ "6000000008684" ], "departmentId" : "6000000007245", "roles" : [ "6000000008686", "6000000011307" ], "name" : "Sales Representatives", "description" : "Sales teams for customer engagement.", "derivedAgents" : [ "6000000009086", "6000000012003" ], "id" : "6000000014005", "subTeams" : [ "6000000011305" ], "agents" : [ "6000000009086", "6000000012003" ] }

Create team

This API creates a team in your help desk portal.

Attributes

Param Name

Data Type

Description

name

String

required

Name of the team

description

String

optional

A short description of the team

departmentId

Long

required

ID of the department to which the team belongs

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

POST /api/v1/teams

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011307", "6000000011309", "6000000011311" ],
  "name" : "Sales Representatives",
  "description" : "Sales teams for customer engagement.",
  "subTeams" : [ "6000000012001" ],
  "agents" : [ "6000000009086" ]
}'

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team teamObj = new Team();
teamObj.setName(name);
teamObj.setDescription(description);
Team response = team.createTeam( teamObj );

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
  "name" : "Sales Representatives",
  "description" : "Sales teams for customer engagement.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000012001" ],
  "agents" : [ "6000000009086" ]
}

Update team

This API updates details of an existing team.

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the team

description

String

optional

A short description of the team

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

PATCH /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/teams/6000000014007
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "roles" : [ "6000000011307", "6000000011311" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "subTeams" : [ "6000000011303" ],
  "agents" : [ "6000000009086" ]
}'

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team teamObj = new Team();
teamObj.setName(name);
teamObj.setDescription(description);
Team response = team.updateTeam( team_id, teamObj );

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011307" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000011303" ],
  "agents" : [ "6000000009086" ]
}

Delete team

This API deletes an existing team from your help desk portal. To reassign the open and on hold tickets and tasks of the deleted team to a different team, pass the ticketNewTeam, taskNewTeam, ticketNewAgent, and taskNewAgent team parameters in the API request. If you do not want to assign the tickets to another team, pass the values of ticketNewTeam and ticketNewAgent as null. However, in the case of tasks, either taskNewTeam or taskNewAgent must have a valid value. Both parameters cannot be passed as null.

Attributes

Param Name

Data Type

Description

ticketNewTeam

long

required

Assign open and on hold tickets of the team being deleted to this team.

ticketNewAgent

long

required

Assign open and on hold tickets of the team being deleted to this agent.

taskNewTeam

long

required

Assign open tasks of the team being deleted to this team.

taskNewAgent

long

required

Assign open tasks of the team being deleted to this agent.

POST /api/v1/teams/{team_id}/deleteTeam

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/teams/6000000014007/deleteTeam
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "ticketNewAgent" : "5000000013005", "ticketNewTeam" : "5000000013001", "taskNewTeam" : "5000000013001", "taskNewAgent" : "5000000013009" }'

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
boolean response = team.deleteTeam( team_id, ticketNewAgent, ticketNewTeam, taskNewTeam, taskNewAgent );

Response Example

Get team

This API fetches the details of a team.

GET /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000014007
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team response = team.getTeam( team_id );

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011307" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000011303" ],
  "agents" : [ "6000000009086" ]
}

List teams from all associated departments

This API fetches details of all teams created in all departments to which the current user belongs.

GET /api/v1/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.listTeamsInCurrentAgentAssociatedDept( );

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000007253",
    "roles" : [ ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ ],
    "id" : "17000000013003",
    "subTeams" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000009326",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ ],
    "id" : "17000000013005",
    "subTeams" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000007253",
    "roles" : [ ],
    "name" : "Engineering",
    "description" : "Developers and Engineers.",
    "derivedAgents" : [ ],
    "id" : "17000000013001",
    "subTeams" : [ ],
    "agents" : [ ]
  } ]
}

List details of team members

This API fetches details of all the members of a particular team.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the team. Values allowed are profile, role. You can include all two values by separating them with commas in the API request.

GET /api/v1/teams/{team_id}/members

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000011303/members
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "members" : [ {
    "firstName" : "",
    "lastName" : "John",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=437793",
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "john@zylker.com",
    "id" : "7000000013328",
    "zuid" : "437793"
  }, {
    "firstName" : "Steve",
    "lastName" : "Kyle",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "kyle@zylker.com",
    "id" : "7000000012958",
    "zuid" : "5625416"
  } ]
}

List associable teams

This API lists the other teams that can be added as sub-teams to the current team.

GET /api/v1/teams/{team_id}/associables

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000011303/associables
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<String> response = team.getSubTeamsIds( team_id );

Response Example

{
  "teams" : [ 6000000011303, 6000000017021, 6000000017023, 6000000016013, 6000000017017, 6000000016015, 6000000017019, 6000000017013, 6000000017015, 6000000017009, 6000000012001, 6000000017011, 6000000017005, 6000000016025, 6000000017007, 6000000017059, 6000000016027, 6000000017001, 6000000016029, 6000000017003, 6000000016031, 6000000016017, 6000000015001, 6000000016019, 6000000016021 ]
}

List associated teams of agent

This API fetches details of all the teams to which an agent belongs.

GET /api/v1/agents/{agent_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/6000000011313/teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.listAssociatedTeamsForAgent( agent_id );

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ "60000000098623" ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ "6000000011313", "60000000120230" ],
    "id" : "6000000083003",
    "subTeams" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "agents" : [ "6000000011313" ]
  } ]
}

List associated teams for a role

This API fetches details of all the teams associated with a particular role.

GET /api/v1/roles/{role_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/roles/6000000008684/teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ "6000000008684" ],
    "departmentId" : "60000000839483",
    "roles" : [ "60000000098623" ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ "6000000011313", "60000000120230" ],
    "id" : "6000000083003",
    "subTeams" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ "6000000008684" ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "agents" : [ "6000000011313" ]
  } ]
}

List teams in department

This API fetches details of all the teams in a particular department.

GET /api/v1/departments/{department_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/6000000007245/teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.getTeamsInDepartment( department_id );

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
    "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
    "departmentId" : "6000000007245",
    "name" : "Field Agents",
    "derivedAgents" : [ "6000000009086" ],
    "description" : "Field Agents team for customer issues",
    "id" : "6000000017039",
    "subTeams" : [ ],
    "agents" : [ "6000000009086" ]
  }, {
    "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
    "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
    "departmentId" : "6000000007245",
    "name" : "Managers",
    "derivedAgents" : [ "6000000009086" ],
    "description" : "Managers",
    "id" : "6000000016007",
    "subTeams" : [ "6000000016011", "6000000014005" ],
    "agents" : [ "6000000009086" ]
  } ]
}

Departments

Departments refer to the organizational divisions configured in your help desk, based on the business function performed by each division; for example, marketing, sales, finance, admin, and so on.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the department

name

string

Name of the department

nameInCustomerPortal

string

Display name of the department in the help center

description

string

A short description of the department

isVisibleInCustomerPortal

boolean

Key that denotes if the department is visible in the help center or not

isEnabled

boolean

Key that denotes if the department is enabled or not

isAssignToTeamEnabled

boolean

Key that denotes if the assign to team functionality is enabled or not

hasLogo

boolean

Key that denotes if the department has a logo or not

creatorId

long

ID of user who created the department

createdTime

timestamp

Time of creating the department

associatedAgentIds

list

IDs of agents associated with the department

isDefault

boolean

Key that denotes if the department is the default department in the help desk portal

chatStatus

string

Chat status of the departments: AVAILABLE, DISABLED, NOT_CREATED

Example

{ "isAssignToTeamEnabled" : true, "chatStatus" : "NOT_CREATED", "hasLogo" : true, "isVisibleInCustomerPortal" : true, "creatorId" : "1892000000042001", "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "isDefault" : true, "isEnabled" : true, "name" : "Zylker", "createdTime" : "2019-07-26T13:11:02.000Z", "id" : "1892000000082069", "nameInCustomerPortal" : "ZylCares" }

Get department

This API fetches the details of a department from your help desk

GET /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000082069
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department response = department.getDepartment( departmentId );

Response Example

{
  "isAssignToTeamEnabled" : true,
  "chatStatus" : "AVAILABLE",
  "hasLogo" : true,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ],
  "isDefault" : true,
  "isEnabled" : true,
  "name" : "Zylker",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082069",
  "nameInCustomerPortal" : "ZylCares"
}

List departments

This API lists a particular number of departments, based on the limit specified.

Query Params

Param Name

Data Type

Description

isEnabled

boolean

optional

Key that filters departments based on their enabled status

from

integer

optional,
range : >=0

Index number, starting from which the departments must be fetched

searchStr

string

optional,
max chars : 100

String to search for departments by name, help center name, or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for departments whose name, help center name, or description start with the string, 2) *string* - Searches for departments whose name, help center name, or description contain the string, 3) string - Searches for departments whose name, help center name, or description is an exact match for the string

limit

integer

optional,
range : 0-200

Number of departments to fetch; default value is 10 and maximum value supported is 200

chatStatus

string

optional,
max chars : 100

Key that filters departments based on their chat status. Values allowed are AVAILABLE, DISABLED, NOT_CREATED, and ${UNAVAILABLE}. ${UNAVAILABLE} refers to departments which are not available for chat.

GET /api/v1/departments

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments?isEnabled=true&chatStatus=AVAILABLE
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
GetDepartmentsFilter filter = new GetDepartmentsFilter.Builder().setChatStatus(chatStatus).build();
List<Department> response = department.getDepartments( from, limit, filter );

Response Example

{
  "data" : [ {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : true,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "Zylker",
    "creatorId" : "1892000000042001",
    "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
    "createdTime" : "2019-07-26T13:11:02.000Z",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : false,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "zPad",
    "creatorId" : "1892000000042001",
    "description" : "zPad is the most advanced tablet that brings you the never-experienced-before processing power.",
    "createdTime" : "2019-08-25T10:12:04.000Z",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

List agents in department

This API lists the agents in a department.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the agents must be listed

limit

integer

optional,
range : 0-200

Number of agents to fetch; default value is 10 and maximum value is 200

status

string

optional,
max chars : 100

Key that filters agents, based on their activation status: ACTIVE or DISABLED

isLightAgent

boolean

optional

Key that denotes if the agents must be light or non light.

isConfirmed

boolean

optional

Key that denotes if the agents must be confirmed or unconfirmed.

searchStr

string

optional,
max chars : 100

fieldName

string

optional,
max chars : 100

Name of the field that must be used for searching and listing agents. Values allowed are: firstName, lastName, name, and emailId.

sortOrder

string

optional,
max chars : 100

To sort the available list of agents in either ascending or descending order. Values allowed are: asc or desc

GET /api/v1/departments/{department_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907/agents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
GetAgentsInDepartmentFilter filter = new GetAgentsInDepartmentFilter.Builder().setFieldName(fieldName).build();
List<Agent> response = department.getAgentsInDepartment( departmentId, from, limit, filter );

Response Example

{
  "data" : [ {
    "lastName" : "case",
    "extn" : "3298",
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "case@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "12121",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "case",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "jade",
    "extn" : "3203",
    "roleId" : "1892000000056899",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "jade@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10657727",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ],
    "firstName" : "",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Email", "Forums" ],
    "name" : "jade",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets",
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "john",
    "extn" : "3228",
    "roleId" : "1892000000056004",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "john@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10713988",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "68779989",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "john",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "Waugh",
    "extn" : "4020",
    "roleId" : "1892000000056004",
    "langCode" : "ja_JP",
    "mobile" : "",
    "emailId" : "stephen@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : null,
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "Steve",
    "photoURL" : null,
    "phone" : "",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat" ],
    "name" : "Steve Waugh",
    "isConfirmed" : false,
    "aboutInfo" : "Expert in handling Departments",
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get department count

This API returns the number of departments configured in your help desk portal.

Query Params

Param Name

Data Type

Description

isEnabled

boolean

optional

Key that filters departments based on their enabled status

GET /api/v1/departments/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907/count?isEnabled=true
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get department details by department IDs

This API fetches the details of the departments whose IDs are passed in the API request.

Query Params

Param Name

Data Type

Description

departmentIds

long

required

Comma-separated array of department IDs. Maximum number of IDs allowed is 50.

GET /api/v1/departmentsByIds?departmentIds={department_ids}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departmentsByIds?departmentIds=1892000000082069,1892000000082085
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : true,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "Zylker",
    "creatorId" : "1892000000042001",
    "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
    "createdTime" : "2019-07-26T13:11:02.000Z",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "DISABLED",
    "isDefault" : false,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "zPad",
    "creatorId" : "1892000000042001",
    "description" : "zPad is the most advanced tablet that brings you the never-experienced-before processing power.",
    "createdTime" : "2018-07-06T13:11:12.000Z",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

Check for duplicate departments

This API checks if multiple departments have the same name.

Query Params

Param Name

Data Type

Description

departmentName

string

required,
max chars : 150

Name of the department for which you want to check duplicate entries

GET /api/v1/departments/checkExists

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/checkExists?departmentName=zPad
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDepartmentNameExist" : true
}

Add department

This API adds a department to your help desk portal.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

Key that denotes if the department is visible in the help center or not

isAssignToTeamEnabled

boolean

optional

Key that denotes if the assign to team functionality is enabled or not

associatedAgentIds

list

required

IDs of agents associated with the department

POST /api/v1/departments

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/departments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "isAssignToTeamEnabled" : false, "isVisibleInCustomerPortal" : true, "name" : "zPhone", "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.", "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ], "nameInCustomerPortal" : "zPhone" }'

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department departmentObj = new Department();
departmentObj.setName(name);
departmentObj.setDescription(description);
departmentObj.setNameInCustomerPortal(nameInCustomerPortal);
Department response = department.createDepartment( departmentObj );

Response Example

{
  "isAssignToTeamEnabled" : false,
  "chatStatus" : "NOT_CREATED",
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "isDefault" : false,
  "isEnabled" : true,
  "name" : "zPhone",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone"
}

Update department

This API updates the details of an existing department.

Attributes

Param Name

Data Type

Description

name

string

optional,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

Key that denotes if the department is visible in the help center or not

isAssignToTeamEnabled

boolean

optional

Key that denotes if the assign to team functionality is enabled or not

associatedAgentIds

list

optional

IDs of agents associated with the department

PATCH /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/departments/1892000000082085
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "isAssignToTeamEnabled" : true, "nameInCustomerPortal" : "zPhone Support" }'

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department departmentObj = new Department();
departmentObj.setNameInCustomerPortal(nameInCustomerPortal);
Department response = department.updateDepartment( departmentId, departmentObj );

Response Example

{
  "isAssignToTeamEnabled" : true,
  "chatStatus" : "DISABLED",
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "isDefault" : false,
  "isEnabled" : true,
  "name" : "zPhone",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone Support"
}

Disable department

This API disables a department in your help desk portal.

Attributes

Param Name

Data Type

Description

agentNewDepartment

Long

required

Agents move to new department ID

emailNewDepartment

Long

optional

Email move to new department ID

POST /api/v1/departments/{department_id}/disable

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/disable
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "emailNewDepartment" : "1892000000082069", "agentNewDepartment" : "1892000000082069" }'

Response Example

Enable department

This API enables a department in your help desk portal.

POST /api/v1/departments/{department_id}/enable

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/enable
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Associate agents to department

This API associates agents to a department.

Attributes

Param Name

Data Type

Description

agentIds

list

required

Ids of Agents

POST /api/v1/departments/{department_id}/associateAgents

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/associateAgents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIds" : [ "1892000000042001", "1892000000056007" ]
}'

Response Example

Dissociate agents from department

This API dissociates agents from a department.

Attributes

Param Name

Data Type

Description

agentIds

list

required

Ids of Agents

POST /api/v1/departments/{department_id}/dissociateAgents

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/dissociateAgents
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIds" : [ "1892000000056007" ]
}'

Response Example

Get department logo

This API fetches the logo set for a department.

Query Params

Param Name

Data Type

Description

fileSize

string

optional,
max chars : 100

Attribute Name

Data Type

Description

type

string

Type of the channel. Possible values are SYSTEM, INTEGRATION, INSTANT_MESSAGE

name

string

Name of the channel

code

string

Unique Identifier Code of the channel

appName

string

Name of the application that handles the channel

photoURL

string

Photo URL of the channel

departmentId

string

Default department ID of the channel in which the tickets will be created unless customized

acceptsReplies

string

Specifies whether the channel accepts replies for tickets or threads

replyConfig

show Attributes

JSONObject

Reply configuration of the channel if the channel accepts replies for tickets or threads

mappedIntegration

string

Type of integration, only if the type is INSTANT_MESSAGE

Example

{ "photoURL" : null, "code" : "EMAIL", "appName" : null, "departmentId" : null, "name" : "EMail", "mappedIntegration" : null, "replyConfig" : { "updateRecords" : false, "acceptsAttachments" : true, "contentTypes" : [ "text/plain", "text/html" ], "includeQuotedMessage" : true }, "type" : "SYSTEM", "acceptsReplies" : true }

Get a Channel

This API gets fetches details of a given channel.

GET /api/v1/channels/{channel_code}?orgId={org_id}

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account?orgId=60856948
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ChannelAPI channel = ZDesk.getChannelAPIInstance(mailId);
Channel response = channel.getChannelByCode( channelCode );

Response Example

{
  "photoURL" : "https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948",
  "code" : "SALES_WHATSAPP_ACCOUNT",
  "appName" : "Sales Whatsapp Account",
  "departmentId" : "76389000000006907",
  "name" : "Sales Whatsapp Account",
  "externalId" : "109000000002003",
  "replyConfig" : {
    "updateRecords" : false,
    "acceptsAttachments" : false,
    "contentTypes" : [ "text/plain" ],
    "includeQuotedMessage" : false
  },
  "type" : "INSTANT_MESSAGE",
  "acceptsReplies" : true
}

List configured channels

This API fetches currently installed channels including System, Channel integration and Instant Messaging channels

GET /api/v1/channels

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/channels
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ChannelAPI channel = ZDesk.getChannelAPIInstance(mailId);
List<Channel> response = channel.getChannels( );

Response Example

{
  "data" : [ {
    "photoURL" : "https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948",
    "code" : "SALES_WHATSAPP_ACCOUNT",
    "appName" : "Sales Whatsapp Account",
    "departmentId" : "76389000000006907",
    "name" : "Sales Whatsapp Account",
    "externalId" : "109000000002003",
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "INSTANT_MESSAGE",
    "acceptsReplies" : true
  }, {
    "photoURL" : "https://desk.zoho.com/api/v1/channels/youtubecat/photo?orgId=647164567",
    "code" : "YOUTUBECAT",
    "appName" : "Youtube Cat",
    "departmentId" : "188422000009189044",
    "name" : "Youtube Cat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "INTEGRATION",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "EMAIL",
    "appName" : null,
    "departmentId" : null,
    "name" : "Email",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : true,
      "contentTypes" : [ "text/plain", "text/html" ],
      "includeQuotedMessage" : true
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "TWITTER",
    "appName" : null,
    "departmentId" : null,
    "name" : "Twitter",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "TWITTER_DM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Twitter",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "FACEBOOK",
    "appName" : null,
    "departmentId" : null,
    "name" : "Facebook",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "FACEBOOK_DM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Facebook",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "WEB",
    "appName" : null,
    "departmentId" : null,
    "name" : "Web",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "ONLINE_CHAT",
    "appName" : null,
    "departmentId" : null,
    "name" : "Chat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "OFFLINE_CHAT",
    "appName" : null,
    "departmentId" : null,
    "name" : "Chat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FORUMS",
    "appName" : null,
    "departmentId" : null,
    "name" : "Forums",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain", "text/html" ],
      "includeQuotedMessage" : true
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "PHONE",
    "appName" : null,
    "departmentId" : null,
    "name" : "Phone",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "ZTI",
    "appName" : null,
    "departmentId" : null,
    "name" : "Phone",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "CUSTOMERPORTAL",
    "appName" : null,
    "departmentId" : null,
    "name" : "Web",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FEEDBACK",
    "appName" : null,
    "departmentId" : null,
    "name" : "FeedBack",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FEEDBACK_WIDGET",
    "appName" : null,
    "departmentId" : null,
    "name" : "Feedback Widget",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  } ]
}

Get Channel logo

This API gets the logo for the given channel.

Query Params

Param Name

Data Type

Description

height

integer

optional

Height Percentage of image to be returned

GET /api/v1/channels/{channel_code}/photo?orgId={org_id}

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Update Channel logo

This API updates the logo for the given channel. Logo of SYSTEM channels cannot be updated.

File Params

photo

Content-Type:multipart/form-data

Maximum file size allowed is 500KB

POST /api/v1/channels/{channel_code}/photo?orgId={org_id}

OAuth Scope

Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Tickets

Tickets are organizing units using which service agents handle customer enquiries, requests, complaints, and other such interactions in Zoho Desk.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the ticket

subject

string

Subject of the ticket

departmentId
see documentation

long

ID of the department to which the ticket belongs

contactId
see documentation

referred object

ID of the contact who raised the ticket. If a value is not available for this key, make sure to include the contact JSON object. If neither attribute is available, an error message regarding the unavailability of the contactId message is returned.

contact

show Attributes

Contact

Details of the contact who raised the ticket. This object is used for automatically creating a contact when a ticket is received. If the email ID of the contact already exists in your portal, the corresponding contactId is used for creating the ticket. Else, a contact is first created and the contactId of the new contact is mapped to the ticket. The user’s profile and field permissions are considered in the contact creation process. Either the lastName or the email attribute must be present in the object.

productId

referred object

ID of the product to which the ticket is mapped

uploads
see documentation

list

File attachments in the ticket. For more information, refer to the Uploads section

string

Email ID in the ticket

phone

string

Phone number in the ticket

description

string

Description in the ticket

status

string

Status of the ticket. Includes the custom statuses configured in your help desk portal.

statusType

string

Type of ticket resolution status.The values supported are OPEN and ON HOLD and CLOSED.

assigneeId

long

ID of agent to whom the ticket is assigned

category

string

Category of the ticket

subCategory

string

Subcategory of the ticket

resolution

string

Resolution notes recorded in the ticket

dueDate

timestamp

Due date for resolving the ticket

priority

string

Priority of the ticket

language

string

Language preference to set for the ticket

responseDueDate

string

Date on or before which a response must be sent for the ticket

channel

string

Channel through which the ticket originated.

channelCode

string

Code of the ticket's source channel

source

show Attributes

object

Details of the ticket source from channel

classification

string

Type of ticket. Values supported are Problem, Request, Question, and Others.

~~customFields~~

deprecated

JSONObject

Custom fields in the ticket

JSONObject

Custom fields in the ticket

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the ticket

modifiedTime

timestamp

Time of modifying the ticket

timeEntryCount

integer

Number of time entries recorded in the ticket

approvalCount

integer

Number of approvals associated with the ticket

commentCount

integer

Number of comments in the ticket

attachmentCount

integer

Number of attachments in the ticket

taskCount

integer

Number of tasks associated with the ticket

threadCount

integer

Number of threads associated in the ticket

isDeleted

boolean

Key that returns if the ticket is deleted or not

isTrashed

boolean

Field that denotes whether the ticket is in trash

product

show Attributes

Product

Product associated with the ticket. You obtain this information using the include:product query parameter to fetch this information.

closedTime

timestamp

Time of closing the ticket

ticketNumber

integer

Index/Serial number of the ticket

customerResponseTime

timestamp

Time of receiving customer response

isRead

boolean

Key that denotes if the current user has read the ticket or not

assignee

show Attributes

object

Agent assigned to resolve the ticket. Use the include:assignee query param to fetch this information.

teamId

long

ID of the team assigned to resolve the ticket

isFollowing

boolean

Key that returns if the current user follows the ticket or not

department

show Attributes

object

Details of the department to which the ticket belongs

team

show Attributes

object

Details of the team assigned to resolve the ticket

channelRelatedInfo

show Attributes

object

Secondary information related to the channel of the ticket. Currently, this key is supported only for the Forums channel. Therefore, the API response will not return this information for tickets received through other channels.

secondaryContacts
see documentation

list

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.

Example

{ "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ], "modifiedTime" : "2016-06-21T13:16:14.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority", "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "onholdTime" : null, "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority", "source" : { "appName" : null, "extId" : null, "type" : "SYSTEM", "permalink" : null, "appPhotoURL" : null }, "resolution" : null, "sharedDepartments" : [ { "name" : "Sample Department Name", "id" : "1892000000006909", "type" : "READ_WRITE" }, { "name" : "Sample Department Name", "id" : "1892000000006911", "type" : "READ_ONLY" } ], "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "isTrashed" : false, "contact" : { "lastName" : "Carol", "firstName" : "Lucas", "phone" : "1 888 900 9646", "mobile" : "8838109870", "id" : "1892000000042032", "isSpam" : false, "type" : "paid", "email" : "carol@zylker.com", "account" : { "website" : "www.desk.com", "accountName" : "desk Account", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "department" : { "name" : "dasdasdasd", "id" : "1892000000006907" }, "email" : "carol@zylker.com", "channelCode" : null, "customerResponseTime" : "2013-11-04T11:21:07.912Z", "product" : null, "cf" : { "cf_permanentaddress" : null, "cf_dateofpurchase" : null, "cf_phone" : null, "cf_numberofitems" : null, "cf_url" : null, "cf_secondaryemail" : null, "cf_severitypercentage" : "0.0", "cf_modelname" : "F3 2017" }, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "secondaryContacts" : [ "1892000000042038", "1892000000042042", "1892000000042056" ], "team" : { "name" : "kjsdfjks", "id" : "8920000000069071" }, "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "teamId" : "8920000000069071", "attachmentCount" : "1", "assignee" : { "firstName" : "dasca", "lastName" : "vins", "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo", "id" : "1892000000056007", "email" : "jack@asdad.com" }, "isSpam" : false, "category" : "general", "status" : "Open" }

Get a ticket

This API fetches a single ticket from your helpdesk.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Key that fetches secondary information related to the ticket. Values allowed are: contacts, products, assignee, departments, contract, isRead, team, and skills . Multiple values can be passed, with commas for separation.

GET /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237?include=contacts,products,assignee,departments,team
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
Ticket response = ticket.getTicket( ticketId, include );

Response Example

{
  "modifiedTime" : "2016-06-21T13:16:14.000Z",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "onholdTime" : null,
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ {
    "name" : "Sample Department Name",
    "id" : "1892000000006909",
    "type" : "READ_WRITE"
  }, {
    "name" : "Sample Department Name",
    "id" : "1892000000006911",
    "type" : "READ_ONLY"
  } ],
  "closedTime" : null,
  "sharedCount" : "3",
  "approvalCount" : "1",
  "isTrashed" : false,
  "contact" : {
    "lastName" : "Carol",
    "firstName" : "Lucas",
    "phone" : "1 888 900 9646",
    "mobile" : "8838486174",
    "id" : "1892000000042032",
    "isSpam" : false,
    "type" : null,
    "email" : "carol@zylker.com",
    "account" : {
      "website" : "www.desk.com",
      "accountName" : "desk Account",
      "id" : "1892000000975382"
    }
  },
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "secondaryContacts" : [ "1892000000042038", "1892000000042042", "1892000000042056" ],
  "priority" : "High",
  "classification" : null,
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false,
  "assignee" : {
    "firstName" : "dasca",
    "lastName" : "vins",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
    "id" : "1892000000056007",
    "email" : "jack@asdad.com"
  },
  "status" : "Open",
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "ticketNumber" : "101",
  "isRead" : false,
  "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : {
    "topicId" : "1892000000056253",
    "isTopicDeleted" : false,
    "forumStatus" : "ANALYSING",
    "sourceLink" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Community/singlepost/problem-topic-forum-ticket-18-5-2018",
    "topicType" : "PROBLEM"
  },
  "isDeleted" : "false",
  "department" : {
    "name" : "dasdasdasd",
    "id" : "1892000000006907"
  },
  "followerCount" : "5",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "product" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "isFollowing" : "true",
  "team" : {
    "name" : "kjsdfjks",
    "id" : "8920000000069071"
  },
  "assigneeId" : "1892000000056007",
  "teamId" : "8920000000069071",
  "contractId" : null,
  "tagCount" : "2",
  "attachmentCount" : "1",
  "category" : "general"
}

List all tickets

This API lists a particular number of tickets, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the tickets must be fetched

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched (Please note that this key will be deprecated soon and replaced by the departmentIds key.)

departmentIds
see documentation

long

optional

Departments from which the tickets need to be queried

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

string

optional,
max chars : 100

assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.

channel

string

optional,
max chars : 100

Filter by channel through which the tickets originated. You can include multiple values by separating them with a comma

status

string

optional,
max chars : 100

Filter by resolution status of the ticket. You can include multiple values by separating them with a comma

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: responseDueDate or customerResponseTime or createdTime or ticketNumber. The default sorting order is ascending. A - prefix denotes descending order of sorting.

receivedInDays

integer

optional

Fetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.

include
see documentation

string

optional,
max chars : 100

Additional information related to the tickets. Values allowed are: contacts, products, departments, team, isRead and assignee. You can pass multiple values by separating them with commas in the API request.

fields

string

optional,
max chars : 100

Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: statusType, webUrl, layoutId. Maximum of 30 fields is supported as comma separated values.

priority

string

optional,
max chars : 100

Key that filters tickets by priority. Multiple priority levels can be passed as comma-separated values.

GET /api/v1/tickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets?include=contacts,assignee,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsFilter filter = new GetTicketsFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTickets( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "onholdTime" : null,
    "language" : "English",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543210",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "isSpam" : false,
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "176",
    "subCategory" : null,
    "statusType" : "Closed",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-01T14:04:07.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Forums",
    "isRead" : false,
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : "9876543211",
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker sAccount",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-06T09:49:50.000Z",
    "id" : "1892000000094004",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "On Hold",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "isRead" : true,
    "onholdTime" : "2014-03-28T12:09:10.736Z",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:16:03.000Z",
    "id" : "1892000000137057",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Custom On Hold"
  } ]
}

List all associated tickets

This API lists a particular number of tickets that are associated to you from your help desk, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the tickets must be listed

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

assignee

string

optional,
max chars : 100

assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.

status

string

optional,
max chars : 100

Filter by resolution status of the ticket. You can include multiple values by separating them with a comma

follower

string

optional,
max chars : 100

Filter by followers of the ticket. Values allowed : a valid agentId.

commenter

string

optional,
max chars : 100

Filter by commenters of the ticket. Values allowed : a valid agentId. As of now, either follower or commenter is supported. If both params are given, commenter will be ignored.

sharedDepartmentId

long

optional

Fetches only the tickets shared from departmentId to sharedDepartmentId. If departmentId is not provided, fetches all the tickets shared to sharedDepartmentId. sharedDepartmentId is given precedence only when isShared is false/not given.

isShared

boolean

optional

Filter all shared tickets actually belonging to departmentId if isShared is true. If departmentId is not provided and if isShared is true, shared tickets from all permitted departments will be listed. If departmentId is provided and isShared is true, tickets belonging to departmentId, but shared to any other department will be fetched. If departmentId and sharedDepartmentId is provided and isShared is true, then tickets belonging to departmentId, but shared to sharedDepartmentId will be fetched(Here permission checks are done on departmentId). If departmentId and sharedDepartmentId is provided and isShared is false/not given, then tickets shared to sharedDepartmentId, but belonging to departmentId will be fetched(Here permission checks are done on sharedDepartmentId).

receivedInDays

integer

optional

Fetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.

include
see documentation

string

optional,
max chars : 100

Key that returns additional information related to a ticket. Values allowed are: contacts, products, and assignee. All three values can be passed by separating them with a comma in the API request.

GET /api/v1/associatedTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/associatedTickets?include=contacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543212",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "email" : "carol@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "176",
    "subCategory" : null,
    "statusType" : "Closed",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-01T14:04:07.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Forums",
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker sAccount",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-06T09:49:50.000Z",
    "id" : "1892000000094004",
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "onholdTime" : "2014-03-28T12:09:10.736Z",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : "9876543212",
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:16:03.000Z",
    "id" : "1892000000137057",
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

Create a ticket

This API creates a ticket in your helpdesk.

Attributes

Param Name

Data Type

Description

subject

string

required,
max chars : 255

Subject of the ticket

departmentId
see documentation

long

required

ID of the department to which the ticket belongs

contactId
see documentation

referred object

optional

contact

Contact

optional

productId

referred object

optional

ID of the product to which the ticket is mapped

uploads
see documentation

list

optional

File attachments in the ticket. For more information, refer to the Uploads section

string

optional,
max chars : 150

Email ID in the ticket

phone

string

optional,
max chars : 120

Phone number in the ticket

description

string

optional,
max chars : 65535

Description in the ticket

status

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

assigneeId

long

optional

ID of agent to whom the ticket is assigned

category

string

optional,
max chars : 300

Category of the ticket

subCategory

string

optional,
max chars : 300

Subcategory of the ticket

resolution

string

optional,
max chars : 65535

Resolution notes recorded in the ticket

dueDate

timestamp

optional

Due date for resolving the ticket

priority

string

optional,
max chars : 120

Priority of the ticket

language

string

optional,
max chars : 255

Language preference to set for the ticket

responseDueDate

string

optional,
max chars : 100

Date on or before which a response must be sent for the ticket

channel

string

optional,
max chars : 120

Channel through which the ticket originated.

classification

string

optional,
max chars : 100

Type of ticket. Values supported are Problem, Request, Question, and Others.

~~customFields~~

deprecated

JSONObject

optional

Custom fields in the ticket

JSONObject

optional

Custom fields in the ticket

webUrl

string

optional,
max chars : -1

URL to access the resource

teamId

long

optional

ID of the team assigned to resolve the ticket

secondaryContacts
see documentation

list

optional

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

optional

Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.

POST /api/v1/tickets

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ], "subCategory" : "Sub General", "cf" : { "cf_permanentaddress" : null, "cf_dateofpurchase" : null, "cf_phone" : null, "cf_numberofitems" : null, "cf_url" : null, "cf_secondaryemail" : null, "cf_severitypercentage" : "0.0", "cf_modelname" : "F3 2017" }, "productId" : "", "contactId" : "1892000000042032", "subject" : "Real Time analysis Requirement", "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hai This is Description", "language" : "English", "priority" : "High", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "general", "email" : "carol@zylker.com", "status" : "Open" }'

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
Ticket ticketObj = new Ticket();
ticketObj.setSubject(subject);
ticketObj.setDescription(description);
ticketObj.setPhone(phone);
ticketObj.setWebUrl(webUrl);
ticketObj.setEmail(email);
ticketObj.setChannelCode(channelCode);
Ticket response = ticket.createTicket( ticketObj );

Response Example

{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "modifiedTime" : "2016-06-21T12:50:04.000Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T18:50:04.573Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Hai This is description",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "channelRelatedInfo" : null,
  "isDeleted" : "false",
  "isTrashed" : false,
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Update a ticket

This API updates an existing ticket.

Query Params

Param Name

Data Type

Description

disableClosureNotification

boolean

optional

Key that enables or disables sending notifications to the corresponding contact when a ticket is closed

Attributes

Param Name

Data Type

Description

subject

string

optional,
max chars : 255

Subject of the ticket

departmentId
see documentation

long

optional

ID of the department to which the ticket belongs

contactId
see documentation

referred object

optional

contact

Contact

optional

productId

referred object

optional

ID of the product to which the ticket is mapped

uploads
see documentation

list

optional

File attachments in the ticket. For more information, refer to the Uploads section

string

optional,
max chars : 150

Email ID in the ticket

phone

string

optional,
max chars : 120

Phone number in the ticket

description

string

optional,
max chars : 65535

Description in the ticket

status

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

assigneeId

long

optional

ID of agent to whom the ticket is assigned

category

string

optional,
max chars : 300

Category of the ticket

subCategory

string

optional,
max chars : 300

Subcategory of the ticket

resolution

string

optional,
max chars : 65535

Resolution notes recorded in the ticket

dueDate

timestamp

optional

Due date for resolving the ticket

priority

string

optional,
max chars : 120

Priority of the ticket

language

string

optional,
max chars : 255

Language preference to set for the ticket

responseDueDate

string

optional,
max chars : 100

Date on or before which a response must be sent for the ticket

channel

string

optional,
max chars : 120

Channel through which the ticket originated.

classification

string

optional,
max chars : 100

Type of ticket. Values supported are Problem, Request, Question, and Others.

~~customFields~~

deprecated

JSONObject

optional

Custom fields in the ticket

JSONObject

optional

Custom fields in the ticket

webUrl

string

optional,
max chars : -1

URL to access the resource

teamId

long

optional

ID of the team assigned to resolve the ticket

secondaryContacts
see documentation

list

optional

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

optional

Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.

PATCH /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/3000000024409
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ], "subCategory" : "Sub General", "cf" : { "cf_permanentaddress" : null, "cf_dateofpurchase" : null, "cf_phone" : null, "cf_numberofitems" : null, "cf_url" : null, "cf_secondaryemail" : null, "cf_severitypercentage" : "0.0", "cf_modelname" : "F3 2017" }, "productId" : "", "contactId" : "1892000000042032", "subject" : "Real Time analysis Requirement", "dueDate" : "2016-06-21T16:16:16.000Z", "channel" : "FORUMS", "description" : "Sample Ticket", "language" : "English", "priority" : "Low", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "general", "email" : "carol@zylker.com", "status" : "Open" }'

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
Ticket ticketObj = new Ticket();
ticketObj.setSubject(subject);
ticketObj.setDescription(description);
ticketObj.setResolution(resolution);
ticketObj.setEmail(email);
ticketObj.setChannelCode(channelCode);
ticketObj.setPhone(phone);
Ticket response = ticket.updateTicket( ticketId, filter, ticketObj );

Response Example

{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "modifiedTime" : "2016-06-21T12:58:09.122Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-23T12:58:09.211Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "onholdTime" : null,
  "description" : "Sample Ticket",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "channelRelatedInfo" : {
    "isTopicDeleted" : false,
    "forumStatus" : "ANALYSING",
    "sourceLink" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Community/singlepost/problem-topic-forum-ticket-18-5-2018",
    "topicType" : "PROBLEM"
  },
  "isDeleted" : "false",
  "isTrashed" : false,
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "Low",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Move Tickets to trash

This API moves tickets to the Recycle Bin

Attributes

Param Name

Data Type

Description

ticketIds

list

required

IDs of the tickets to move to the Recycle Bin

POST /api/v1/tickets/moveToTrash

OAuth Scope

Desk.tickets.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ticketIds" : [ "2000032002032" ]
}'

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
boolean response = ticket.moveToTrash( ticketIds );

Response Example

Merge two tickets

This API merges two different tickets.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of the tickets to merge

source

show Attributes

object

optional

JSON object of the tickets to merge

POST /api/v1/tickets/{ticket_id}/merge

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000008749/merge
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "4000000018011" ],
  "source" : {
    "contactId" : "4000000018011",
    "subject" : "4000000018011",
    "priority" : "4000000018011",
    "status" : "4000000018011"
  }
}'

Response Example

{
  "entitySkills" : [ "42000000000364001", "42000000000379001", "42000000000379031" ],
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "42000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Real Time analysis Requirement",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "4000000008749",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "42000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "42000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Move ticket

This API helps move a ticket from one department to another. Note: The departmentId query parameter will be deprecated soon. Therefore, going forward, the departmentId attribute must be passed in the body of the API request.

Query Params

Param Name

Data Type

Description

departmentId
see documentation

long

optional

ID of the department to which you want to move the ticket

Attributes

Param Name

Data Type

Description

departmentId

long

optional

ID of the department in which the ticket exists

forumId

long

optional

ID of the community sub-category to which the forum ticket (forum topic converted into a ticket) must be moved

POST /api/v1/tickets/{ticket_id}/move

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000093303/move
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "departmentId" : "1892000000082069", "forumId" : "1892000000052355" }'

Response Example

Split tickets

This API splits a thread into a ticket.

POST /api/v1/tickets/{ticket_id}/thread/{thread_id}/split

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000047005/threads/1892000000133023/split
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Real Time analysis Requirement",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Bulk update tickets

This API updates multiple tickets at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/tickets/updateMany

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "subject", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "Ticket for support" }'

Response Example

Closed many tickets

This API closes multiple tickets at once.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of tickets to close

POST /api/v1/closeTickets

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/closeTickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ]
}'

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
boolean response = ticket.closeTickets( ids );

Response Example

Mark as read

This API marks a ticket as read by the user.

POST api/v1/tickets/{ticket_id}/markAsRead

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000988091/markAsRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Mark as unread

This API marks a ticket as unread by the user.

POST api/v1/tickets/{ticket_id}/markAsUnRead

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000988091/markAsUnRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Mark ticket as spam

This API marks tickets as spam.

Attributes

Param Name

Data Type

Description

isSpam

boolean

required

Key that marks or unmarks a single ticket or multiple tickets as spam

ids

list

required

ID(s) of the ticket(s) that must be marked or unmarked as spam

contactSpam

boolean

optional

Key that marks or unmarks the associated contact as spam

handleExistingTickets

boolean

optional

Key that marks or unmarks the other tickets from the contact(s) as spam

POST /api/v1/tickets/markSpam

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/markSpam
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contactSpam" : "true",
  "handleExistingTickets" : "true",
  "ids" : [ "1000000121176", "1000000016435", "1000000016435" ],
  "isSpam" : "true"
}'

Response Example

List all ticketQueueView count

This API returns the number of tickets in a particular view.

Query Params

Param Name

Data Type

Description

viewId

long

required

ID of the view whose ticket count must be fetched

departmentId
see documentation

String

required

ID of the department from which the ticket count must be fetched

agentId

long

optional

ID of the agent assigned to resolve the tickets

GET api/v1/ticketQueueView/count

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketQueueView/count?viewId=40000000004567&departmentId=allDepartment
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

List all agentsTicketsCount

This API returns the number of tickets assigned to multiple agents.

Query Params

Param Name

Data Type

Description

departmentId
see documentation

String

optional

ID of the department from which the ticket count must be fetched. To fetch ticket count of agents from all departments, pass the value allDepartments.

agentIds

long

optional

IDs of the agents whose ticket count must be fetched

GET api/v1/agentsTicketsCount

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agentsTicketsCount?agentIds=4000000008734,4000000056010
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
List<Map<String, Object>> response = ticket.getAgentsTicketsCount(agentIds, departmentId );

Response Example

{
  "data" : [ {
    "onholdCount" : 1,
    "agentId" : "4000000008734",
    "dueIn1HrCount" : 0,
    "overDueCount" : 2,
    "channel" : [ "Mail", "Phone" ],
    "isOnline" : true,
    "openCount" : 18
  }, {
    "onholdCount" : 1,
    "agentId" : "4000000056010",
    "dueIn1HrCount" : 0,
    "overDueCount" : 0,
    "isOnline" : false,
    "openCount" : 0
  } ]
}

Get ticket history

This API fetches details of all actions — called events — performed on a ticket and in the sub-tabs on the ticket detail page. To view a detailed documentation for this API, visit this page.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0

Index number, starting from which the events must be fetched

limit

int

optional,
range : 1-50

Number of events to list

eventFilter

string

optional,
max chars : 100

Key that filters events, based on their type. Values allowed are: CommentHistory, TimeEntryHistory, TaskHistory, CallHistory, EventHistory, AttachmentHistory, ApprovalHistory, SuperviseHistory, WorkflowHistory, MacroHistory, AssignmentRuleHistory, NotificationRuleHistory, SLAHistory, BlueprintHistory and SkillRelatedHistory

agentId

long

optional

Key that filters details of actions performed by a particular agent. Value allowed is the agent's ID in Zoho Desk.

fieldName

string

optional,
max chars : 100

Key that filters the history of a particular field. The value for this key must be the apiName of the field.

GET api/v1/tickets/{ticket_id}/History

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/7000000025045/History?eventFilter=CommentHistory
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "actor" : {
      "name" : "Aadavan",
      "id" : "7000000025001",
      "type" : "Contact"
    },
    "eventInfo" : [ {
      "propertyName" : "Department",
      "propertyType" : "Entity",
      "systemProperty" : true,
      "propertyValue" : {
        "name" : "Zylker Primary",
        "id" : "7000000013224",
        "type" : "Department"
      }
    }, {
      "propertyName" : "Account Name",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Primary Account"
    }, {
      "propertyName" : "Contact Name",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Aadavan"
    }, {
      "propertyName" : "Email",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "aathavan@gmail.com"
    }, {
      "propertyName" : "Subject",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Ticket Subject"
    }, {
      "propertyName" : "Description",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "<div>Description.<br /></div>"
    }, {
      "propertyName" : "Status",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Open"
    }, {
      "propertyName" : "Case Owner",
      "propertyType" : "Entity",
      "systemProperty" : true,
      "propertyValue" : {
        "name" : "Imman",
        "id" : "7000000000059",
        "type" : "Agent"
      }
    }, {
      "propertyName" : "Channel",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Email"
    }, {
      "propertyName" : "Is Escalated",
      "propertyType" : "Boolean",
      "systemProperty" : true,
      "propertyValue" : false
    } ],
    "eventTime" : "2020-06-03T11:14:52.000Z",
    "eventName" : "TicketCreated",
    "source" : "Email",
    "actorInfo" : [ ]
  } ]
}

Get ticket resolution

This API fetches details related to the resolution of a ticket.

GET api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2015-12-12T00:00:00Z",
  "author" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
    "id" : 160200000000068000,
    "email" : "saranraj.shanugam@zohocorp.com"
  },
  "content" : "test resolution API"
}

Get resolution history

This API fetches the resolution history of a ticket

Query Params

Param Name

Data Type

Description

from

int

optional

Index number starting from which records must be fetched

limit

int

optional,
range : 1-100

Number of records to fetch

GET api/v1/tickets/{ticket_id}/resolutionHistory

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/resolutionHistory
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2015-12-12T00:00:00Z",
    "author" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
      "id" : 160200000000068000,
      "email" : "saranraj.shanugam@zohocorp.com"
    },
    "content" : "update ticket resolution"
  }, {
    "modifiedTime" : "2015-11-12T00:00:00Z",
    "author" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
      "id" : 160200000000068000,
      "email" : "saranraj.shanugam@zohocorp.com"
    },
    "content" : "add ticket resolution"
  } ]
}

Update ticket resolution

This API updates the resolution field of a ticket.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content to add in the field

isNotifyContact

boolean

optional

Key that specifies if the contact associated must be notified about the resolution

PATCH api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isNotifyContact" : false,
  "content" : "test resolution API"
}'

Response Example

{
  "modifiedTime" : "2015-12-12T00:00:00Z",
  "author" : {
    "firstName" : "pandi",
    "lastName" : "raj",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
    "id" : 160200000000068000,
    "email" : "pandeeswaran@edu.com"
  },
  "content" : "test resolution API"
}

Delete ticket resolution

This API deletes a resolution added to a ticket.

DELETE api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get ticket metrics

This API fetches details related to the response and resolution times of a ticket.

GET /api/v1/tickets/([0-9]+)/metrics

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000085990/metrics
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
TicketMetricsResp response = ticket.getTicketsMetrics( ticketId );

Response Example

{
  "firstResponseTime" : "01:50 hrs",
  "reassignCount" : 1,
  "outgoingCount" : 2,
  "threadCount" : 2,
  "totalResponseTime" : "02:50 hrs",
  "responseCount" : 1,
  "agentsHandled" : [ {
    "agentId" : 4000000012629,
    "avgHandlingTime" : "00:50 hrs",
    "agentName" : "XXX"
  }, {
    "agentId" : 4000000080003,
    "avgHandlingTime" : "01:50 hrs",
    "agentName" : "YYY"
  } ],
  "resolutionTime" : "02:50 hrs",
  "stagingData" : [ {
    "handledTime" : "01:50 hrs",
    "status" : "Open"
  }, {
    "handledTime" : "00:50 hrs",
    "status" : "onhold"
  } ],
  "reopenCount" : 0
}

Delete spam tickets

This API deletes all spam tickets.

Attributes

Param Name

Data Type

Description

departmentId
see documentation

long

required

ID of the department to which the tickets belong

POST /api/v1/tickets/emptySpam

OAuth Scope

Desk.tickets.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/emptySpam
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "departmentId" : "1892000000006907"
}'

Response Example

Execute Skill Based Assignment

This API assigns tickets to agents according to their designated skills and routing preferences.

POST /api/v1/tickets/{ticket_id}/executeSkillbasedAssignment

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1000000159323/executeSkillbasedAssignment?orgId=15157826
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isAssigned" : true,
  "newAssignee" : {
    "photoURL" : "https://desk.zoho.zohocorpin.com/api/v1/agents/1000000000059/photo?orgId=111111",
    "firstName" : "Alex",
    "lastName" : "John",
    "name" : "Alex",
    "roleName" : null,
    "externalId" : null,
    "emailId" : "alex@zylker.com",
    "id" : "1000000000059",
    "type" : "AGENT",
    "email" : "alex@zylker.com",
    "zuid" : "1231232"
  },
  "team" : {
    "name" : "Automation Team",
    "id" : "1000000000089"
  }
}

Recalculate Skills

This API removes existing skills and reapplies the required ones based on the ticket's current circumstances.

POST /api/v1/tickets/{ticket_id}/recalculateSkills

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1000000159323/recalculateSkills
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-24T07:36:33.000Z",
  "skillsInfo" : [ {
    "weightage" : "10",
    "skillName" : "Middle East",
    "skillId" : "1000000174138",
    "skillTypeId" : "1000000173007",
    "mappingType" : "SYSTEM",
    "skillTypeName" : "Region"
  }, {
    "weightage" : "9",
    "skillName" : "Asia",
    "skillId" : "1000000174140",
    "skillTypeId" : "1000000173007",
    "mappingType" : "SYSTEM",
    "skillTypeName" : "Region"
  } ],
  "modifiedBy" : "1000000032001",
  "id" : "1000000170017"
}

Suggest relevant articles for ticket

This API suggests help articles that could be relevant to resolving a ticket.

Query Params

Param Name

Data Type

Description

from

int

optional,
range : >=0

Index number, starting from which the articles must be fetched

limit

int

optional,
range : 1-50

Number of articles to list

departmentId

long

optional

ID of the department to which the help article belongs. If you want to include help articles from all departments, pass 0 as the value of this key

GET /api/v1/tickets/{ticket_id}/articleSuggestion

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/22372000000103001/articleSuggestion?departmentId=40000000012359orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-06-24T11:46:43.000Z",
    "creatorId" : "4000000000059",
    "dislikeCount" : "0",
    "modifierId" : "4000000000059",
    "likeCount" : "0",
    "locale" : "en",
    "ownerId" : "4000000000059",
    "title" : "Answering your first ticket.",
    "isTrashed" : false,
    "createdTime" : "2020-06-24T11:46:43.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019059",
    "viewCount" : "0",
    "owner" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
    "latestVersionStatus" : "Published",
    "myVote" : null,
    "author" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "permission" : "AGENTS",
    "authorId" : "4000000000059",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "4000000017276",
    "translationId" : "4000000017294",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "latestVersion" : "1.0",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "feedbackCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
    "attachmentCount" : "0",
    "latestPublishedVersion" : "1.0",
    "category" : {
      "name" : "General",
      "id" : "4000000017287",
      "locale" : "en"
    },
    "permalink" : "answering-your-first-ticket",
    "categoryId" : "4000000017287",
    "status" : "Published"
  } ]
}

Queue APIs

Ticket queues refer to the views in which tickets are grouped and listed according to their due time left for resolution, status, priority, or contact type in Zoho CRM. These queues appear as Countdown Mode, Status Mode, Priority Mode, and Handshake Mode respectively, on Zoho Desk.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the ticket

subject

string

Subject of the ticket

departmentId
see documentation

long

ID of the department to which the ticket belongs

contactId
see documentation

referred object

contact

show Attributes

Contact

productId

referred object

ID of the product to which the ticket is mapped

uploads
see documentation

list

File attachments in the ticket. For more information, refer to the Uploads section

string

Email ID in the ticket

phone

string

Phone number in the ticket

description

string

Description in the ticket

status

string

Status of the ticket. Includes the custom statuses configured in your help desk portal.

statusType

string

Type of ticket resolution status.The values supported are OPEN and ON HOLD and CLOSED.

assigneeId

long

ID of agent to whom the ticket is assigned

category

string

Category of the ticket

subCategory

string

Subcategory of the ticket

resolution

string

Resolution notes recorded in the ticket

dueDate

timestamp

Due date for resolving the ticket

priority

string

Priority of the ticket

language

string

Language preference to set for the ticket

responseDueDate

string

Date on or before which a response must be sent for the ticket

channel

string

Channel through which the ticket originated.

channelCode

string

Code of the ticket's source channel

source

show Attributes

object

Details of the ticket source from channel

classification

string

Type of ticket. Values supported are Problem, Request, Question, and Others.

~~customFields~~

deprecated

JSONObject

Custom fields in the ticket

JSONObject

Custom fields in the ticket

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the ticket

modifiedTime

timestamp

Time of modifying the ticket

timeEntryCount

integer

Number of time entries recorded in the ticket

approvalCount

integer

Number of approvals associated with the ticket

commentCount

integer

Number of comments in the ticket

attachmentCount

integer

Number of attachments in the ticket

taskCount

integer

Number of tasks associated with the ticket

threadCount

integer

Number of threads associated in the ticket

isDeleted

boolean

Key that returns if the ticket is deleted or not

isTrashed

boolean

Field that denotes whether the ticket is in trash

product

show Attributes

Product

Product associated with the ticket. You obtain this information using the include:product query parameter to fetch this information.

closedTime

timestamp

Time of closing the ticket

ticketNumber

integer

Index/Serial number of the ticket

customerResponseTime

timestamp

Time of receiving customer response

isRead

boolean

Key that denotes if the current user has read the ticket or not

assignee

show Attributes

object

Agent assigned to resolve the ticket. Use the include:assignee query param to fetch this information.

teamId

long

ID of the team assigned to resolve the ticket

isFollowing

boolean

Key that returns if the current user follows the ticket or not

department

show Attributes

object

Details of the department to which the ticket belongs

team

show Attributes

object

Details of the team assigned to resolve the ticket

channelRelatedInfo

show Attributes

object

secondaryContacts
see documentation

list

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.

Example

{ "modifiedTime" : "2016-06-21T13:16:14.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "onholdTime" : null, "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority", "resolution" : null, "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "isTrashed" : false, "contact" : { "lastName" : "Carol", "firstName" : "Lucas", "phone" : "1 888 900 9646", "mobile" : "8834567908", "id" : "1892000000042032", "type" : "paid", "email" : "carol@zylker.com", "account" : { "website" : "www.desk.com", "accountName" : "desk Account", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "department" : { "name" : "dasdasdasd", "id" : "1892000000006907" }, "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "product" : null, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "team" : { "name" : "kjsdfjks", "id" : "8920000000069071" }, "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "teamId" : "8920000000069071", "attachmentCount" : "1", "assignee" : { "firstName" : "dasca", "lastName" : "vins", "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo", "id" : "1892000000056007", "email" : "jack@asdad.com" }, "category" : "general", "status" : "Open" }

List tickets by CRMType

This API lists tickets in OPEN and ON HOLD state by contact types as categorized in Zoho CRM.

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which the tickets must be listed

limit

int

optional,
range : 1-50

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

crmContactType
see documentation

string

required,
max chars : 100

Contact type as set in Zoho CRM. Values allowed are unmapped, contacts_leads, potentials, and customers

include
see documentation

string

optional,
max chars : 100

GET /api/v1/ticketsByCrmContactType

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketsByCrmContactType?departmentId=1892000000006907&crmContactType=unmapped&include=contacts,assignee,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsByCrmContactTypeFilter filter = new GetTicketsByCrmContactTypeFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTicketsByCrmContactType( from, limit, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : true,
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8834567908",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "statusType" : "On Hold",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "isRead" : true,
    "channel" : "Facebook",
    "onholdTime" : "2014-03-06T11:34:53.000Z",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "mobile" : "8812345608",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebbcaefeb9d93ba74750b02843cad3b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "On Hold"
  } ]
}

List tickets by due minutes

This API lists tickets by the due time for resolution.

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which the tickets must be listed

limit

int

optional,
range : 1-50

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

dueInMinutes
see documentation

integer

required

Number of minutes left for resolving the ticket. Currently, the minimum number of minutes is 15 and the maximum is 2,880. This query param can return overdue and no-due tickets too. Values allowed are overDue, 15, 30, 45, 60, 90, 120, 180, 360, 540, 720, 1080, 1440, 2880, noDue, and onhold.

include
see documentation

string

optional,
max chars : 100

GET /api/v1/ticketsByDueInMinutes

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketsByDueInMinutes?departmentId=1892000000006907&dueInMinutes=overDue&include=contacts,assignee,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketByDueInMinutesFilter filter = new GetTicketByDueInMinutesFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTicketByDueInMinutes( from, limit, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : true,
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "mobile" : "8834567907",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Facebook",
    "isRead" : true,
    "onholdTime" : null,
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "mobile" : "8834534901",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebc54aeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

List tickets by status

This API fetches tickets by resolution status which is mapped to either OPEN or ON HOLD

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which the tickets must be listed

limit

int

optional,
range : 1-50

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

status
see documentation

string

required,
max chars : 100

Status of the ticket. Includes the custom statuses configured in your help desk

include
see documentation

string

optional,
max chars : 100

GET /api/v1/ticketsByStatus

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketsByStatus?departmentId=1892000000006907&status=ON Hold&include=contacts,assignee,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsByStatusFilter filter = new GetTicketsByStatusFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTicketsByStatus( from, limit, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "statusType" : "On Hold",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "onholdTime" : "2016-06-21T16:16:16.000Z",
    "language" : "English",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "mobile" : "8834562344",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247ca87daeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "On Hold"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "statusType" : "On Hold",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Facebook",
    "isRead" : true,
    "onholdTime" : "2014-03-06T11:34:53.000Z",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "mobile" : "8832345108",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9eb9bb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "On Hold"
  } ]
}

Threads

Threads are conversations that occur between agents and customers. A thread can originate from multiple channels, such as FACEBOOK, TWITTER, EMAIL, TWITTER_DM, WEB, ONLINE_CHAT, OFFLINE_CHAT, FORUMS, TWILIO, ZTI, CUSTOMERPORTAL, FEEDBACK, FEEDBACK_WIDGET.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the thread

channel

string

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

status

string

Status of the thread.Values supported are SUCCESS,PENDING,FAILED,DRAFT

content

string

Content of the thread

contentType

string

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

createdTime

timestamp

Time of creating the thread

direction

string

Key that returns whether the thread is incoming or outgoing

author

show Attributes

object

Details of the user who created the thread

fromEmailAddress
see documentation

string

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

string

To email ID in the thread, applicable only for EMAIL channel

string

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

phoneno

string

Phone number through which the thread originated, applicable only for the ZTI and TWILIO

summary

string

Summary of the thread

attachments

show Attributes

object

Attachments in the thread

hasAttach

boolean

States whether the thread has attachments

isDescriptionThread

boolean

Key that denotes if the thread is the description of the ticket

channelRelatedInfo

show Attributes

object

Secondary information related to the channel of the thread. Currently, this key is supported only for the Forums channel. Therefore, the API response will not return this information for threads generated through other channels

actions

list

Actions available from the present state which will be included based on present status.It is a collection of all actions and each action has a rel,href and method.The respective links and methods to be invoked will be available under the 'href' and 'method' key for each action.

respondedIn

string

Time taken by the agent to respond to the customer

canReply

boolean

Specifies whether replies can be added be added to this thread.

source

show Attributes

object

Details of the thread source from channel

Example

{ "summary" : "How was our Customer Service", "attachments" : [ { "size" : "1913", "name" : "ScreenShot", "id" : "1892000001083005", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "canReply" : true, "visibility" : "public", "author" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade@zylker.zohodesk.com" }, "channel" : "FORUMS", "source" : { "appName" : null, "extId" : null, "type" : "SYSTEM", "permalink" : null, "appPhotoURL" : null }, "content" : "How was our Customer Service ?", "hasAttach" : true, "createdTime" : "2016-03-21T08:46:48.248Z", "id" : "1892000000135387", "actions" : [ ], "contentType" : "text/html", "status" : "SUCCESS", "direction" : "out" }

Get a thread

This API fetches a single thread from your help desk portal.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Content of the thread in plain text format. Value allowed is plainText.

GET /api/v1/tickets/{ticket_id}/threads/{thread_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000135387?include=plainText
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.getThread( threadId, ticketId, include );

Response Example

{
  "isDescriptionThread" : true,
  "attachments" : [ {
    "size" : "1913",
    "name" : "ScreenShot",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "bcc" : "",
  "isContentTruncated" : true,
  "canReply" : true,
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "<div>Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation</div>",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "plainText" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "id" : "1892000000135387",
  "contentType" : "text/html",
  "direction" : "in",
  "cc" : "",
  "summary" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@gmail.com"
  },
  "fullContentURL" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/fullContent",
  "isForward" : false,
  "hasAttach" : true,
  "replyTo" : "jhonwin@gmail.com",
  "attachmentCount" : "1",
  "to" : "techsupport@zylker.zohodesk.com",
  "fromEmailAddress" : "jade12tywin@gmail.com",
  "actions" : [ ],
  "status" : "SUCCESS"
}

Get Latest thread

This API fetches the most recent thread recorded in a ticket.

Query Params

Param Name

Data Type

Description

needPublic

boolean

optional,
default : false

Key that denotes if the thread must be a public thread

include
see documentation

string

optional,
max chars : 100

Content of the thread in plain text format. Value allowed is plainText.

threadStatus

string

optional,
max chars : 100

Receipt status of the thread. Value allowed is success

GET /api/v1/tickets/{ticket_id}/latestThread

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/latestThread
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "cc" : "",
  "summary" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "attachments" : [ {
    "size" : "1913",
    "name" : "ScreenShot",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "bcc" : "",
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "isForward" : false,
  "hasAttach" : true,
  "replyTo" : "jhonwin@gmail.com",
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "to" : "techsupport@zylker.zohodesk.com",
  "id" : "1892000001083008",
  "fromEmailAddress" : "jade12tywin@gmail.com",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "in"
}

Send For Review

This API saves drafts of agent's responses to customers and sends them to a manager/senior agent for review.

POST /api/v1/tickets/{ticket_id}/threads/{thread_id}/sendForReview

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000012313/sendForReview
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List all threads

This API lists all threads in your helpdesk.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the threads must be fetched

limit

integer

required,
default : 100,
range : 1-200

Number of threads to fetch

GET /api/v1/tickets/{ticket_id}/threads

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/threads
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
List<Thread> response = thread.getThreads( ticketId, from, limit );

Response Example

{
  "data" : [ {
    "isDescriptionThread" : true,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "FORUMS",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : null,
    "hasAttach" : false,
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true"
    },
    "respondedIn" : null,
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "7",
    "id" : "1892000000413186",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "summary" : "Customer Rating",
    "cc" : "",
    "isDescriptionThread" : false,
    "bcc" : "",
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "EMAIL",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "isForward" : false,
    "hasAttach" : true,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : null,
    "respondedIn" : "00:05:14",
    "createdTime" : "2016-05-25T10:06:09.686Z",
    "attachmentCount" : "4",
    "id" : "1892000001004072",
    "to" : "carol@zoho.com",
    "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/resendFailedThread?threadId=1892000001083008"
    } ],
    "contentType" : "text/html",
    "status" : "FAILED",
    "direction" : "out"
  }, {
    "summary" : "Please fix this problem, since it is urgent posted the issue on Facebook ",
    "isDescriptionThread" : false,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FACEBOOK",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : "https://desk.zoho.com/api/v1/ratingOptions/31138000005998227/logo?orgId=54983163",
    "hasAttach" : false,
    "responderId" : "2150000000043591",
    "channelRelatedInfo" : null,
    "respondedIn" : "00:04:09",
    "createdTime" : "2016-07-25T10:04:43.739Z",
    "attachmentCount" : "6",
    "id" : "2150000002498038",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
    }, {
      "method" : "DELETE",
      "rel" : "delete",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
    } ],
    "contentType" : "text/html",
    "status" : "DRAFT",
    "direction" : "out"
  }, {
    "isDescriptionThread" : false,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "FEEDBACK",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : null,
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "respondedIn" : null,
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "5",
    "id" : "1892000000413189",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  } ]
}

List conversations

This API lists a particular number of threads and comments recorded on a ticket, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the conversations must be fetched

limit

integer

required,
default : 100,
range : 1-200

Number of conversations to fetch

GET /api/v1/tickets/{ticket_id}/conversations

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000321001/conversations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "We have found the root cause for the issue and fixed it. How would you rate our customer service? Good Okey Bad",
    "isDescriptionThread" : true,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FORUMS",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "type" : "thread",
    "lastRatingIconURL" : "https://desk.zoho.com/api/v1/ratingOptions/31138000005998227/logo?orgId=54983163",
    "isForward" : false,
    "hasAttach" : false,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true"
    },
    "respondedIn" : "00:05:14",
    "createdTime" : "2016-07-07T10:12:04.177Z",
    "attachmentCount" : "7",
    "id" : "1892000001080014",
    "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "out"
  }, {
    "summary" : "Any update regarding the issue",
    "cc" : "productmanagement@zylker.zohodesk.com",
    "isDescriptionThread" : false,
    "bcc" : "",
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : null,
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "EMAIL",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "type" : "thread",
    "lastRatingIconURL" : null,
    "isForward" : false,
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "respondedIn" : null,
    "createdTime" : "2016-07-07T10:02:04.663Z",
    "attachmentCount" : "6",
    "id" : "1892000001080004",
    "to" : "techsupport@zylker.zohodesk.com",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "modifiedTime" : "2016-02-16T14:12:20.000Z",
    "commentedTime" : "2016-02-16T09:21:58.000Z",
    "isPublic" : true,
    "id" : "1892000000886025",
    "type" : "comment",
    "content" : "There is a major issue with the real time dashboard feature . Kindly look into it",
    "commenterId" : "1892000000042001",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Send Reply via Integrated Custom Channels

This API sends a reply to any of the configured non-system channels. The channel must be able to handle the reply otherwise the reply will fail. Available channels to be used in this API can be fetched using Get Channels API.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "channel" : "YOUTUBE", "content" : "Thank you for your valueable comment." }'

Response Example

{
  "summary" : "Thank you for your valueable comment.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "YOUTUBE",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thank you for your valueable comment.",
  "isForward" : false,
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "Zylker Vlogs",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "PENDING",
  "direction" : "out"
}

Send Email Reply

This API sends an email reply. The from address in the email must be a from address configured in your help desk portal.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

-d'{ "channel" : "EMAIL", "attachmentIds" : [ "1312123141313" ], "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "contentType" : "plainText", "content" : "We have identified the root cause and fixed it.", "isForward" : "true" }'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.sendEmailReply( ticketId, attachmentIds, to, fromEmailAddress, contentType, content, isForward );

Response Example

{
  "summary" : "We have identified the root cause and fixed it.",
  "cc" : "",
  "isDescriptionThread" : true,
  "bcc" : "",
  "attachments" : [ {
    "size" : "818",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We have identified the root cause and fixed it.",
  "isForward" : true,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "PENDING",
  "direction" : "out"
}

Send Facebook Reply

This API adds a reply to a Facebook post

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

-d'{ "channel" : "FACEBOOK", "content" : "We are looking into the issue." }'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.sendFaceBookReply( ticketId, content );

Response Example

{
  "summary" : "We are looking into the issue.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We are looking into the issue.",
  "hasAttach" : false,
  "responderId" : "2150000000043591",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:04:43.739Z",
  "id" : "2150000002498038",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Send Twitter Reply

This API sends a reply to a tweet.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

-d'{ "channel" : "TWITTER", "content" : "The problem has been fixed. Sorry for the inconvenience caused." }'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.sendTwitterReply( ticketId, content );

Response Example

{
  "summary" : "The problem has been fixed. Sorry for the inconvenience caused.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "TWITTER",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:01:14.536Z",
  "id" : "2150000002498018",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Send Forum Reply

This API sends a reply to a comment on a forum post. While using this API, make sure to add the _ZohoDiscussions.basic.ALL_ scope in the request.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  -d'{
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback"
}'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.sendForumsReply( ticketId, content );

Response Example

{
  "summary" : "Thanks for your feedback",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true"
  },
  "createdTime" : "2016-07-25T09:50:03.578Z",
  "id" : "1892000001121138",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Draft Email Reply

This API drafts an email reply. The from address in the email must be a from address configured in your help desk portal.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "channel" : "EMAIL", "attachmentIds" : [ "1312123141313" ], "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "contentType" : "plainText", "content" : "We have escaled the issue. Will update you regarding the progress.", "isForward" : "true" }'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.draftEmailReply( ticketId, attachmentIds, to, fromEmailAddress, contentType, content, isForward );

Response Example

{
  "summary" : "We have escaled the issue. Will update you regarding the progress.",
  "cc" : "",
  "isDescriptionThread" : false,
  "bcc" : "",
  "attachments" : [ {
    "size" : "324",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We have escaled the issue. Will update you regarding the progress.",
  "isForward" : false,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Draft Facebook Reply

This API drafts a reply to a Facebook post.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  -d'{
  "channel" : "FACEBOOK",
  "content" : "The issue has been fixed"
}'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.draftFaceBookReply( ticketId, content );

Response Example

{
  "summary" : "The issue has been fixed",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "The issue has been fixed",
  "hasAttach" : false,
  "responderId" : "2150000000043591",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:04:43.739Z",
  "id" : "2150000002498038",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Draft Forum Reply

This API drafts a reply to a forum post.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  -d'{
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback"
}'

ThreadAPI thread = ZDesk.getThreadAPIInstance(mailId);
Thread response = thread.draftForumsReply( ticketId, content );

Response Example

{
  "summary" : "Thanks for your feedback",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true"
  },
  "createdTime" : "2016-07-25T09:50:03.578Z",
  "id" : "1892000001121138",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Update Draft

This API updates a draft thread created via the EMAIL, FACEBOOK, or FORUM channel.

Attributes

Param Name

Data Type

Description

channel

string

optional,
max chars : 100

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

content

string

optional,
max chars : 16000000

Content of the thread

contentType

string

optional,
max chars : 100

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

optional

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

optional

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

optional

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

optional

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

direction

string

optional,
max chars : 100

Key that returns whether the thread is incoming or outgoing

fromEmailAddress
see documentation

string

optional,
max chars : 300

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

string

optional,
max chars : 13000

To email ID in the thread, applicable only for EMAIL channel

string

optional,
max chars : 13000

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

optional,
max chars : 13000

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

hasAttach

boolean

optional

States whether the thread has attachments

PATCH /api/v1/tickets/{ticket_id}/draftReply/{thread_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "channel" : "EMAIL", "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "contentType" : "plainText", "content" : "We are analysing the issue currently , will update you with a solution as early as possible" }'

Response Example

{
  "summary" : "We are analysing the issue currently , will update you with a solution as early as possible",
  "cc" : "",
  "isDescriptionThread" : false,
  "bcc" : "",
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We are analysing the issue currently , will update you with a solution as early as possible",
  "isForward" : false,
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Delete attachment

This API deletes an attachment from a draft thread.

DELETE /api/v1/tickets/{ticket_id}/threads/{thread_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Contacts

Contacts are the end-customers who raise requests or make enquiries/complaints with your customer service team. Each contact is mapped to an account.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the contact

~~customFields~~

deprecated

object

User-defined fields related to the contact

JSONObject

User-defined fields related to the contact

lastName

string

Last name of the contact

firstName

string

First name of the contact

facebook

string

Facebook ID of the contact

twitter

string

Twitter ID of the contact

secondaryEmail

string

Secondary email ID of the contact

string

Email ID of the contact

phone

string

Phone number of the contact

mobile

string

Mobile number of the contact

city

string

Contact's city of residence

country

string

Contact's country of residence

state

string

Contact's state of residence

street

string

Contact's address

zip

string

Zip code

description

string

Contact description

title

string

Contact title

type

string

Contact type

ownerId

long

ID of the user who creates the contact

owner

show Attributes

object

Details of the user to whom the contact is assigned.

accountId
see documentation

long

Account to which the contact is mapped

zohoCRMContact

show Attributes

object

Contact details fetched from Zoho CRM

customerHappiness

show Attributes

object

Average customer happiness rating of the contact

isDeleted

boolean

Key that returns if the contact is deleted or not

isTrashed

boolean

Field that denotes whether the contact is in trash

isSpam

boolean

Field that denotes whether the contact is spam

photoURL

string

URL of the file containing the image of the contact

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the contact

modifiedTime

timestamp

Time of modifying the contact

Example

{ "lastName" : "Smith", "modifiedTime" : "2015-03-02T14:49:32.000Z", "country" : null, "secondaryEmail" : null, "city" : null, "description" : null, "ownerId" : "3263000000057001", "type" : null, "title" : null, "photoURL" : null, "twitter" : null, "isDeleted" : false, "isTrashed" : false, "street" : null, "createdTime" : "2015-02-16T14:46:24.000Z", "zohoCRMContact" : { "id" : "5000000014010", "type" : "potentials" }, "state" : null, "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "id" : "3263000000064001", "email" : "lawrence@zylker.com", "zip" : null, "cf" : { "cf_permanentaddress" : null, "cf_lastcontactedon" : null }, "isFollowing" : "true", "facebook" : null, "mobile" : null, "accountId" : null, "firstName" : "Jade", "phone" : "123 99 888 23", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "isSpam" : false }

Get Contact

This API fetches a single contact from your help desk portal.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Allowed values are : accounts , owner

GET /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000000042032?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
Contact response = contact.getContact( contactId, include );

Response Example

{
  "lastName" : "Lawrence",
  "modifiedTime" : "2016-05-04T09:57:17.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "description" : null,
  "ownerId" : "1892000000042001",
  "type" : null,
  "title" : null,
  "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
  "twitter" : null,
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "contacts_leads"
  },
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "state" : null,
  "id" : "1892000000042032",
  "email" : "lawrence@zylker.com",
  "zip" : null,
  "owner" : {
    "firstName" : "Twin",
    "lastName" : "john",
    "id" : "1892000000042001"
  },
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : null,
  "mobile" : null,
  "accountId" : "1892000000975382",
  "firstName" : "Jennifer",
  "isAnonymous" : false,
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

List contacts

This API lists a particular number of contacts, based on the limit specified.

Query Params

Param Name

Data Type

Description

include
see documentation

list

optional

Secondary information related to the contact.Value supported is accounts.

from

integer

optional

Index number, starting from which the contacts must be fetched

limit

string

optional,
max chars : 100,
range : 1-100

Number of contacts to fetch

viewId

integer

optional

ID of the view to apply while fetching the resources

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: firstName, lastName, or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: photoURL, webUrl. Maximum of 30 fields is supported as comma separated values.

GET /api/v1/contacts

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
GetContactsFilter filter = new GetContactsFilter.Builder().setViewId(viewId).build();
List<Contact> response = contact.getContacts( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "mobile" : "+91 8508569683",
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : false,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T14:46:24.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "mobile" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : false,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T14:46:24.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

Create Contact

This API creates a contact in your help desk portal.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

object

optional

User-defined fields related to the contact

JSONObject

optional

User-defined fields related to the contact

lastName

string

required,
max chars : 200

Last name of the contact

firstName

string

optional,
max chars : 100

First name of the contact

facebook

string

optional,
max chars : 300

Facebook ID of the contact

twitter

string

optional,
max chars : 300

Twitter ID of the contact

secondaryEmail

string

optional,
max chars : 100

Secondary email ID of the contact

string

optional,
max chars : 255

Email ID of the contact

phone

string

optional,
max chars : 100

Phone number of the contact

mobile

string

optional,
max chars : 100

Mobile number of the contact

city

string

optional,
max chars : 100

Contact's city of residence

country

string

optional,
max chars : 100

Contact's country of residence

state

string

optional,
max chars : 100

Contact's state of residence

street

string

optional,
max chars : 250

Contact's address

zip

string

optional,
max chars : 100

Zip code

description

string

optional,
max chars : 65535

Contact description

title

string

optional,
max chars : 120

Contact title

type

string

optional,
max chars : 120

Contact type

ownerId

long

optional

ID of the user who creates the contact

accountId
see documentation

long

optional

Account to which the contact is mapped

POST /api/v1/contacts

OAuth Scope

Desk.contacts.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "zip" : "123902", "lastName" : "Jack", "country" : "USA", "secondaryEmail" : "hughjack@zylker.com", "city" : "Texas", "facebook" : "hugh jacks", "mobile" : "+10 2328829010", "description" : "first priority contact", "ownerId" : "1892000000056007", "type" : "paidUser", "title" : "The contact", "accountId" : "1892000000052077", "firstName" : "hugh", "twitter" : "Hugh jack", "phone" : "91020080878", "street" : "North street", "state" : "Austin", "email" : "jack@zylker.com" }'

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
Contact contactObj = new Contact();
contactObj.setCountry(country);
contactObj.setLastName(lastName);
contactObj.setSecondaryEmail(secondaryEmail);
contactObj.setCity(city);
contactObj.setFacebook(facebook);
contactObj.setMobile(mobile);
Contact response = contact.createContact( contactObj );

Response Example

{
  "lastName" : "Jack",
  "modifiedTime" : "2016-07-26T13:11:02.000Z",
  "country" : "USA",
  "secondaryEmail" : "hughjack@zylker.com",
  "city" : "Texas",
  "description" : "first priority contact",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "photoURL" : null,
  "twitter" : "Hugh jack",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : "North street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "Austin",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "jack@zylker.com",
  "zip" : "123902",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : "hugh jack",
  "mobile" : "+10 2328829010",
  "accountId" : "1892000000052077",
  "firstName" : "hugh",
  "isAnonymous" : false,
  "phone" : "91020080878",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

Update a contact

This API updates details of an existing contact.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

object

optional

User-defined fields related to the contact

JSONObject

optional

User-defined fields related to the contact

lastName

string

optional,
max chars : 200

Last name of the contact

firstName

string

optional,
max chars : 100

First name of the contact

facebook

string

optional,
max chars : 300

Facebook ID of the contact

twitter

string

optional,
max chars : 300

Twitter ID of the contact

secondaryEmail

string

optional,
max chars : 100

Secondary email ID of the contact

string

optional,
max chars : 255

Email ID of the contact

phone

string

optional,
max chars : 100

Phone number of the contact

mobile

string

optional,
max chars : 100

Mobile number of the contact

city

string

optional,
max chars : 100

Contact's city of residence

country

string

optional,
max chars : 100

Contact's country of residence

state

string

optional,
max chars : 100

Contact's state of residence

street

string

optional,
max chars : 250

Contact's address

zip

string

optional,
max chars : 100

Zip code

description

string

optional,
max chars : 65535

Contact description

title

string

optional,
max chars : 120

Contact title

type

string

optional,
max chars : 120

Contact type

ownerId

long

optional

ID of the user who creates the contact

accountId
see documentation

long

optional

Account to which the contact is mapped

PATCH /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/1892000001128052
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "zip" : "123902",
  "lastName" : "john"
}'

Response Example

{
  "lastName" : "john",
  "modifiedTime" : "2016-07-26T13:11:02.000Z",
  "country" : "USA",
  "secondaryEmail" : "stephen@zylker.com",
  "city" : "Texas",
  "description" : "first priority contact",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "photoURL" : null,
  "twitter" : "stephen john",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : "East street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "Austin",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "stephent@zylker.com",
  "zip" : "123902",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : "Steve john",
  "mobile" : "+129737289298",
  "accountId" : "1892000000052077",
  "firstName" : "Stephen",
  "isAnonymous" : "false",
  "phone" : "8981901921",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

Delete Contacts

This API moves the contacts specified to the Recycle Bin.

Attributes

Param Name

Data Type

Description

contactIds

list

required

IDs of the contacts to move to the Recycle Bin

POST /api/v1/contacts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contactIds" : [ "2000032002145" ]
}'

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
boolean response = contact.moveToTrash( contactIds );

Response Example

Get Contact Profiles

This api fetches the list of profiles of this contact from various channels.

Query Params

Param Name

Data Type

Description

include
see documentation

list

optional

Additional information related to the profile's channel. Values allowed are: source

GET /api/v1/contacts/{contact_id}/profiles

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/18289300000002/profiles
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : "https://www.youtube.com/user/iwe3in2/photo",
    "displayName" : "Jade Vlogs",
    "name" : "Jade Zylker",
    "channel" : "YOUTUBE",
    "id" : "3923923923",
    "source" : {
      "appName" : "Youtube Sync App",
      "permalink" : "https://www.examplechannel.com/apps/redirect.php?entity=profile&id=3290dweiod",
      "appPhotoURL" : "https://desk.zoho.com/api/v1/channels/youtube/photo?orgId=666236571"
    }
  }, {
    "photoURL" : "https://www.intagram.com/johninsta/photo",
    "displayName" : "John Insta",
    "name" : "John Zylker",
    "channel" : "INSTAGRAM",
    "id" : "3923923924",
    "source" : {
      "appName" : "Instagram Syncing App",
      "permalink" : "https://www.examplechannel.com/apps/redirect.php?entity=profile&id=3290dweiod",
      "appPhotoURL" : "https://desk.zoho.com/api/v1/channels/instagram/photo?orgId=666236571"
    }
  } ]
}

Update many contacts

This API updates multiple contacts at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/contacts/updateMany

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "mobile", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "8508569875" }'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

List Contacts By Ids

This API lists details of specific contacts, based on the IDs passed in the request.

Query Params

Param Name

Data Type

Description

ids

long

required

List of Contact Ids (separated by comma) which must be fetched

GET /api/v1/contacts/contactsByIds

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/contactsByIds?ids=1892000000772001,1892000000772003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
List<Contact> response = contact.getContactsByIds(ids );

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "mobile" : "+91 8508569683",
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : false,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "mobile" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : false,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "isSpam" : false,
    "email" : "jade@zylker.com"
  } ]
}

List tickets by contact

This API lists tickets received from a specific contact.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

Additional information related to the tickets. Values allowed are: products, departments, team, isRead and assignee. You can pass multiple values by separating them with a comma in the API request.

GET /api/v1/contacts/{contact_id}/tickets

OAuth Scope

Desk.search.READ , Desk.tickets.READ , Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/18944000000421011/tickets?include=departments,team,assignee
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsByContactFilter filter = new GetTicketsByContactFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTicketsByContact( contactId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zohodesk.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "status" : "Open"
  } ]
}

List products by contact

This API lists products associated for a specific contact.

Query Params

Param Name

Data Type

Description

from

integer

optional

From index

limit

integer

optional,
range : 1-100

Number of products to fetch

departmentId
see documentation

long

optional

Department from which the products need to be queried

GET /api/v1/contacts/{contact_id}/products

OAuth Scope

Desk.products.READ , ~~Desk.settings.READ~~ , ~~Desk.contacts.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000009277/products
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
GetProductsUnderContactFilter filter = new GetProductsUnderContactFilter.Builder().setDepartmentId(departmentId).build();
List<Product> response = product.getProductsUnderContact( contactId, from, limit, filter );

Response Example

{
  "data" : [ {
    "unitPrice" : "0.0",
    "productCode" : null,
    "id" : "4000000012009",
    "productName" : "Dell"
  } ]
}

Get contacts count

This API displays the count for the number of contacts in a custom view

Query Params

Param Name

Data Type

Description

viewId

long

required

Custom view ID

startsWith

String

optional

Displays the number of contacts whose first name or last name begins with the letter you specify. Displays the total number of contacts if you do not specify a letter.

GET api/v1/contacts/count

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/count?viewId=4000227563021&startsWith=A
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

Get contact statistics

This API fetches the overall statistics of an contact.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the statistics must be fetched. If you do not pass this parameter in the API request, statistics from all permitted departments will be fetched.

GET /api/v1/contacts/{contact_id}/statistics

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000227563022/statistics
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "firstResponseTime" : "120000",
  "openTickets" : "11",
  "responseTime" : "13150000",
  "spamTickets" : "0",
  "totalTickets" : "11",
  "customerHappiness" : {
    "badCount" : "50",
    "goodCount" : "0",
    "okCount" : "50"
  },
  "resolutionTime" : "0",
  "channelWiseCount" : {
    "Web" : "3",
    "Forums" : "4",
    "Chat" : "4"
  },
  "onholdTickets" : "2",
  "escalatedTickets" : "0",
  "overdueTickets" : "0"
}

Merge Contacts

This API merges two or more contacts

Note:
Though portal users (users who signed up via the help center) are saved as contacts in the help desk, their records cannot be merged with other records/contacts.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the contacts to merge

source

show Attributes

object

optional

JSON object containing details of the contact

POST /api/v1/contacts/{contact_id}/merge

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/1892000000042032/merge
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "ids" : [ "4000000018011", "4000000018021" ], "source" : { "zip" : "4000000018011", "lastName" : "4000000018011", "country" : "4000000018011", "secondaryEmail" : "4000000018011", "cf" : { "cf_permanentaddress" : 1892220000042001 }, "city" : "4000000018011", "facebook" : "4000000018011", "mobile" : "4000000018011", "description" : "4000000018011", "type" : "4000000018011", "title" : "4000000018011", "firstName" : "4000000018011", "accountId" : "4000000018011", "twitter" : "4000000018011", "phone" : "4000000018011", "street" : "4000000018011", "email" : "4000000018011" } }'

Response Example

{
  "lastName" : "Lawrence",
  "modifiedTime" : "2016-05-04T09:57:17.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "description" : null,
  "ownerId" : "1892000000042001",
  "type" : null,
  "title" : null,
  "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
  "twitter" : null,
  "isDeleted" : false,
  "street" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "contacts_leads"
  },
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "state" : null,
  "id" : "1892000000042032",
  "email" : "lawrence@zylker.com",
  "zip" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : null,
  "mobile" : null,
  "accountId" : "1892000000975382",
  "firstName" : "Jennifer",
  "isAnonymous" : false,
  "phone" : "1 888 900 9646",
  "isSpam" : false
}

Mark contact as spam

This API marks contacts as spam.

Attributes

Param Name

Data Type

Description

ids

list

required

ID(s) of the contact(s) that must be marked or unmarked as spam

isSpam

boolean

required

Key that marks or unmarks a single contact or multiple contacts as spam

handleExistingTickets

boolean

optional

Key that marks or unmarks tickets from the contact(s) as spam

POST /api/v1/contacts/markSpam

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/markSpam
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "handleExistingTickets" : "true",
  "ids" : [ "1000000030065", "1000000030068" ],
  "isSpam" : "true"
}'

Response Example

{
  "results" : [ {
    "success" : false,
    "id" : "1000000030068",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : true,
    "id" : "1000000030063",
    "errors" : null
  } ]
}

Associate products with a contact

This API associates products with a contact.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of the resources to associate

departmentId
see documentation

long

optional

ID of the department containing the products

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/contacts/{contact_id}/associateProducts

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/7000000027081/associateProducts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "departmentId" : "7000000062800",
  "ids" : [ "7000000027223", "7000000043968" ],
  "associate" : true
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  }, {
    "success" : false,
    "id" : "7000000043968",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Get contact history

This API fetches the ticket history of a contact.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the history details must be fetched

agentId

long

optional

Key that filters ticket activities performed by a particular agent

from

Integer

optional

Index number, starting from which the history details must be fetched

limit

Integer

optional,
range : 1-100

Number of history details to fetch

GET api/v1/contacts/{contact_id}/history

OAuth Scope

Desk.tickets.READ , Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000012934/history
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "156648",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "recipients" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012999",
    "dueDate" : null,
    "eventTime" : "2019-09-19T09:37:11.000Z",
    "priority" : null,
    "operation" : "Comment_Updated",
    "ticketId" : "4000000012999",
    "status" : "Open"
  }, {
    "ticketNumber" : "125289",
    "statusType" : "Open",
    "subject" : "Ticket subject here.",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "recipients" : [ "ragavan@gmail.com", "kannan@gmail.com", "thamizharasi@gmail.com" ],
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012807",
    "dueDate" : null,
    "eventTime" : "2019-07-22T16:27:20.000Z",
    "priority" : null,
    "operation" : "Mail_Response_Forward",
    "ticketId" : "4000000012807",
    "status" : "Open"
  } ]
}

Invite multiple contacts to help center

This API helps invite multiple contacts as end-users to your help center.

Attributes

Param Name

Data Type

Description

contactIds

list

required

IDs of the contacts to invite

helpCenterId

long

required

ID of the help center to which you want to add the contacts

POST api/v1/contacts/inviteAsEndUser

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/inviteAsEndUser
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "helpCenterId" : "4000000021302",
  "contactIds" : [ "4000000012902", "40000000212902", "40000002129122" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Invite contact to help center

This API helps invite a particular contact as an end-user to your help center.

Attributes

Param Name

Data Type

Description

helpCenterId

long

required

ID of the help center to which you want to add the contact

POST api/v1/contacts/{contact_id}/inviteAsEndUser

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/40000000212902/inviteAsEndUser
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "helpCenterId" : "4000000021302"
}'

Response Example

Delete contact photo

This API deletes the display picture of a contact.

DELETE api/v1/contacts/{contact_id}/photo

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/40000000212902/photo
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get status of contact in help centers

This API fetches a particular contact's activation status in all the help centers they are part of.

Query Params

Param Name

Data Type

Description

helpCenterId

Long

optional

To get specific helpcenter info

GET api/v1/contacts/{contact_id}/helpCenters

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/40000000212902/helpcenters
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "helpCenter" : {
      "name" : "Zoho",
      "id" : "4000000016038",
      "url" : "https://help.zoho.com/portal/zoho",
      "status" : "ACTIVE"
    },
    "userStatus" : "ACTIVE",
    "userId" : "4000000023791"
  }, {
    "helpCenter" : {
      "name" : "CRM",
      "id" : "4000010498403",
      "url" : "https://help.zoho.com/portal/crm",
      "status" : "ACTIVE"
    },
    "userStatus" : "ACTIVE",
    "userId" : "4000000023791"
  } ]
}

Accounts

Account refers to customer organizations that use your products or services. An account can have multiple contacts.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the account

~~customFields~~

deprecated

list

User-defined fields associated with the account

JSONObject

User-defined fields associated with the account

accountName

string

Name of the account

string

Email ID of the account

website

string

Website of the account

fax

string

Fax number of the account

ownerId

long

ID of account owner

owner

show Attributes

object

Details of the user to whom the account is assigned.

associatedSLAIds

list

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

Industry in which the account operates

city

string

City in which the account is based

country

string

Country in which the account is based

state

string

State in which the account is based

street

string

Address of the account

code

string

Zip code

description

string

A short description of the account

phone

string

Phone number of the account

annualrevenue

double

Annual revenue of the account

createdTime

timestamp

Time of creating the account

modifiedTime

timestamp

Time of modifying the account

isTrashed

boolean

Field that denotes whether the account is in trash

webUrl

string

URL to access the resource

Example

{ "country" : "USA", "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : "www.zylker.com", "code" : "4436", "cf" : { "cf_contactcount" : "1" }, "isFollowing" : "true", "accountName" : "Zylker", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "description" : null, "industry" : "Automation", "zohoCRMAccount" : { "id" : "32754000000537001" }, "ownerId" : "3263000000057001", "isDeleted" : false, "isTrashed" : false, "phone" : "9382991011", "street" : null, "annualrevenue" : null, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "createdTime" : "2015-02-16T16:57:44.000Z", "id" : "3263000000074571", "state" : null, "fax" : "+1 444 8439 2350", "email" : "support@zylker.com" }

Get Account

This API fetches an account from your help desk portal.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Allowed values are : owner

GET /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
Account response = account.getAccount( accountId, include );

Response Example

{
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "code" : "3211",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : "Automation",
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : null,
  "annualrevenue" : null,
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : "+1 444 8656 8732",
  "email" : "support@zylker.com",
  "owner" : {
    "firstName" : "Twin",
    "lastName" : "john",
    "id" : "3263000000057001"
  },
  "website" : "www.zylker.com",
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "phone" : "6218129190",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38"
}

List accounts

This API lists a particular number of accounts, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the accounts must be listed

limit

integer

optional,
range : 1-100

Number of accounts to fetch

viewId

long

optional

ID of the view to apply while fetching the resources

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: accountName or createdTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: photoURL, webUrl. Maximum of 30 fields is supported as comma separated values.

GET /api/v1/accounts

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
GetAccountsFilter filter = new GetAccountsFilter.Builder().setViewId(viewId).build();
List<Account> response = account.getAccounts( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "website" : "112121",
    "accountName" : "Admin Account",
    "phone" : "121212",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "customerHappiness" : {
      "badPercentage" : "30",
      "okPercentage" : "30",
      "goodPercentage" : "40"
    },
    "id" : "1892000000052077",
    "email" : "admin@zylker.com"
  }, {
    "website" : "1211212",
    "accountName" : "Agent Account",
    "phone" : "11211",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "customerHappiness" : {
      "badPercentage" : "20",
      "okPercentage" : "40",
      "goodPercentage" : "40"
    },
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

Create Account

This API creates an account in your help desk portal.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields associated with the account

JSONObject

optional

User-defined fields associated with the account

accountName

string

required,
max chars : 200

Name of the account

string

optional,
max chars : 150

Email ID of the account

website

string

optional,
max chars : 120

Website of the account

fax

string

optional,
max chars : 100

Fax number of the account

ownerId

long

optional

ID of account owner

associatedSLAIds

list

optional

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

optional,
max chars : 120

Industry in which the account operates

city

string

optional,
max chars : 100

City in which the account is based

country

string

optional,
max chars : 100

Country in which the account is based

state

string

optional,
max chars : 100

State in which the account is based

street

string

optional,
max chars : 250

Address of the account

code

string

optional,
max chars : 100

Zip code

description

string

optional,
max chars : 65535

A short description of the account

phone

string

optional,
max chars : 100

Phone number of the account

annualrevenue

double

optional

Annual revenue of the account

POST /api/v1/accounts

OAuth Scope

Desk.contacts.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "accountName" : "Zylker",
  "phone" : "98348229382"
}'

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
Account accountObj = new Account();
accountObj.setCountry(country);
accountObj.setWebsite(website);
accountObj.setCode(code);
accountObj.setCity(city);
accountObj.setAccountName(accountName);
accountObj.setDescription(description);
Account response = account.createAccount( accountObj );

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "cf" : {
    "cf_contactcount" : null
  },
  "isFollowing" : "true",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : null,
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "phone" : "98348229382",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Update Account

This API updates details of an existing account.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields associated with the account

JSONObject

optional

User-defined fields associated with the account

accountName

string

optional,
max chars : 200

Name of the account

string

optional,
max chars : 150

Email ID of the account

website

string

optional,
max chars : 120

Website of the account

fax

string

optional,
max chars : 100

Fax number of the account

ownerId

long

optional

ID of account owner

associatedSLAIds

list

optional

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

optional,
max chars : 120

Industry in which the account operates

city

string

optional,
max chars : 100

City in which the account is based

country

string

optional,
max chars : 100

Country in which the account is based

state

string

optional,
max chars : 100

State in which the account is based

street

string

optional,
max chars : 250

Address of the account

code

string

optional,
max chars : 100

Zip code

description

string

optional,
max chars : 65535

A short description of the account

phone

string

optional,
max chars : 100

Phone number of the account

annualrevenue

double

optional

Annual revenue of the account

PATCH /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/3263000000074571
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "accountName" : "Zylker Agents",
  "phone" : "82301023900123"
}'

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "accountName" : "Zylker Agents",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : null,
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "phone" : "82301023900123",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Delete Accounts

This API moves the accounts specified to the Recycle Bin.

Attributes

Param Name

Data Type

Description

accountIds

list

required

IDs of the accounts to move to the Recycle Bin

POST /api/v1/accounts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "accountIds" : [ "2000032003232" ]
}'

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
boolean response = account.moveToTrash( accountIds );

Response Example

Get contract

Getting contracts of an Account

Query Params

Param Name

Data Type

Description

from

integer

optional

From index,DEFAULT 1

limit

integer

optional,
range : 1-50

Number of contracts to fetch, Ranges from 1-50, DEFAULT 50

departmentId

long

optional

ID of the department from which the contracts must be fetched

contractStatus

string

optional,
max chars : 100

Contract Status,Indicates the Current Status of the Contract, Values are ACTIVE, EXPIRED, FUTURE

GET /api/v1/accounts/{account_id}/contracts

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571/contracts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "slaName" : "Priority-based SLAs",
    "endDate" : "2016-07-16",
    "slaGroupId" : "4000000007069",
    "departmentId" : "4000000007043",
    "contractId" : "4000000032003",
    "contractNumber" : "1212",
    "description" : "contract for all desk account",
    "contractName" : "Contract for desk account",
    "ownerId" : "4000000008692",
    "startDate" : "2016-06-16"
  } ]
}

List all contracts count

This API lists the number of contracts made with the account.

Query Params

Param Name

Data Type

Description

viewId

long

required

Custom view Id

departmentId
see documentation

String

required

Mandatory param to fetch the count of the contracts for a given ID of a department. You can also provide department as allDepartment to fetch the count of the contracts from all the departments

ownerId

long

optional

Displays the number of contracts of only a particular owner

GET api/v1/contracts/count

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contracts/count?viewId=4000227563021&departmentId=4000000007096&ownerId=4000227563909
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

List all accounts count

Get accounts count

Query Params

Param Name

Data Type

Description

viewId

long

required

Custom view ID

startsWith

String

optional

Displays the number of accounts whose first name or last name begins with the letter you specify. Displays the total number of accounts if you do not specify a letter.

GET api/v1/accounts/count

OAuth Scope

Desk.contacts.READ

Request Example

Response Example

{
  "count" : "10"
}

List Associated contacts

This API lists the contacts associated with an account

Query Params

Param Name

Data Type

Description

from

int

optional

From index

limit

integer

optional,
range : 1-100

No. of contacts to fetch

sortBy

string

optional,
max chars : 100

Parameter that sorts contacts by one of these attributes:
firstName,

lastName,

fullName,

phone,

email,

createdTime,

modifiedTime

isSpam

boolean

optional,
default : false

Filters Spam contacts

GET api/v1/accounts/{accounts_id}/contacts?from={from}&limit={limit}&sortBy={sortingField}

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000008784/contacts?from=0&limit=20&sortBy=-fullName
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
GetContactsUnderAccountFilter filter = new GetContactsUnderAccountFilter.Builder().setIsSpam(isSpam).build();
List<Contact> response = account.getContactsUnderAccount( accountId, from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "lastName" : "Lawrence",
    "secondaryEmail" : null,
    "mobile" : "+91 8508569683",
    "type" : null,
    "ownerId" : "4000000008734",
    "firstName" : null,
    "accountId" : "4000000008784",
    "photoURL" : null,
    "isAnonymous" : true,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : "false",
    "zohoCRMContact" : {
      "id" : "5000000014010",
      "type" : "contacts_leads"
    },
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "id" : "4000000008786",
    "isSpam" : false,
    "email" : "support@zylker.com"
  } ]
}

List tickets by account

This API lists tickets received from a specific account.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

GET /api/v1/accounts/{account_id}/tickets

OAuth Scope

Desk.search.READ , Desk.tickets.READ , Desk.accounts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/18944000000421015/tickets?include=assignee,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
GetTicketsByAccountFilter filter = new GetTicketsByAccountFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = account.getTicketsByAccount( accountId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8845678909",
      "id" : "18944000000421011",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zohodesk.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "status" : "Open"
  } ]
}

List products by account

This API lists products associated for a specific account.

Query Params

Param Name

Data Type

Description

from

integer

optional

From index

limit

integer

optional,
range : 1-100

Number of products to fetch

departmentId
see documentation

long

optional

Department from which the products need to be queried

GET /api/v1/accounts/{account_id}/products

OAuth Scope

Desk.products.READ , ~~Desk.settings.READ~~ , ~~Desk.contacts.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000026005/products
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
GetProductsUnderAccountFilter filter = new GetProductsUnderAccountFilter.Builder().setDepartmentId(departmentId).build();
List<Product> response = product.getProductsUnderAccount( accountId, from, limit, filter );

Response Example

{
  "data" : [ {
    "unitPrice" : "0.0",
    "productCode" : null,
    "id" : "4000000012009",
    "productName" : "Dell"
  } ]
}

Merge Accounts

This API merges two or more accounts.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the accounts to merge

source

show Attributes

object

optional

JSON object containing details of the account

POST /api/v1/accounts/{account_id}/merge

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000008749/merge
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "ids" : [ "4000000018011", "4000000018033" ], "source" : { "country" : "4000000018011", "website" : "4000000018011", "code" : "4000000018011", "cf" : { "cf_contactcount" : 1892220000042001 }, "city" : "4000000018011", "description" : "4000000018011", "industry" : "4000000018011", "phone" : "4000000018011", "annualrevenue" : "4000000018011", "street" : "4000000018011", "state" : "4000000018011", "fax" : "4000000018011", "email" : "4000000018011" } }'

Response Example

{
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : "www.zylker.com",
  "code" : "3211",
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : "Automation",
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "phone" : "6218129190",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : "+1 444 8656 8732",
  "email" : "support@zylker.com"
}

Associate products with an account

This API associates products with an account.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of the resources to associate

departmentId
see documentation

long

optional

ID of the department containing the products

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/accounts/{account_id}/associateProducts

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/7000000043860/associateProducts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "departmentId" : "7000000062800",
  "ids" : [ "7000000027223", "7000000043968" ],
  "associate" : true
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  }, {
    "success" : false,
    "id" : "7000000043968",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Update many accounts

This API updates multiple accounts at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/accounts/updateMany

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "phone", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "8508569875" }'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Get account history

This API fetches the ticket history of an account.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the history details must be fetched

agentId

long

optional

Key that filters ticket activities performed by a particular agent

contactId

long

optional

Key that filters ticket activities related to a particular contact

from

Integer

optional

Index number, starting from which the history details must be fetched

limit

Integer

optional,
range : 1-100

Number of history details to fetch

GET api/v1/accounts/{account_id}/history

OAuth Scope

Desk.tickets.READ , Desk.accounts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000012234/history
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "156648",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "recipients" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012999",
    "dueDate" : null,
    "eventTime" : "2019-09-19T09:37:11.000Z",
    "priority" : null,
    "operation" : "Comment_Updated",
    "ticketId" : "4000000012999",
    "status" : "Open"
  }, {
    "ticketNumber" : "125289",
    "statusType" : "Open",
    "subject" : "Ticket subject here.",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "recipients" : [ "ragavan@gmail.com", "kannan@gmail.com", "thamizharasi@gmail.com" ],
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012807",
    "dueDate" : null,
    "eventTime" : "2019-07-22T16:27:20.000Z",
    "priority" : null,
    "operation" : "Mail_Response_Forward",
    "ticketId" : "4000000012807",
    "status" : "Open"
  } ]
}

Get account statistics

This API fetches the overall statistics of an account.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the statistics must be fetched. If you do not pass this parameter in the API request, statistics from all permitted departments will be fetched.

GET /api/v1/accounts/([0-9]+)/statistics

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/([0-9]+)/statistics
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "firstResponseTime" : "120000",
  "openTickets" : "11",
  "responseTime" : "13150000",
  "spamTickets" : "0",
  "totalTickets" : "11",
  "customerHappiness" : {
    "badCount" : "50",
    "goodCount" : "0",
    "okCount" : "50"
  },
  "resolutionTime" : "0",
  "channelWiseCount" : {
    "Web" : "3",
    "Forums" : "4",
    "Chat" : "4"
  },
  "escalatedTickets" : "0",
  "overdueTickets" : "0"
}

List account SLAs

This API lists a particular number of SLAs associated with an account, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
range : >=0

Index number, starting from which the SLAs must be fetched

limit

integer

optional,
range : 1-100

Number of SLAs to list

departmentId

long

optional

ID of the department from which the SLAs must be fetched. If you do not pass this parameter in the API request, SLAs from all permitted departments will be listed.

status

String

optional

Activation status of the SLAs. Values allowed are: ACTIVE and INACTIVE

GET /api/v1/accounts/{account_id}/sla

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571/sla
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "slaName" : "Priority-based SLAs",
    "id" : "45794000000419372",
    "isActive" : true,
    "department" : {
      "name" : "Tesla",
      "id" : "45794000000418059"
    }
  }, {
    "slaName" : "SLA",
    "id" : "45794000000570017",
    "isActive" : true,
    "department" : {
      "name" : "BMW",
      "id" : "45794000000006907"
    }
  }, {
    "slaName" : "Silver SLAs",
    "id" : "45794000000587464",
    "isActive" : true,
    "department" : {
      "name" : "Jaguar",
      "id" : "45794000000586067"
    }
  } ]
}

Associate or dissociate SLA from account

This API associates or dissociates an SLA from an account.

Attributes

Param Name

Data Type

Description

associate

boolean

required

Key that specifies if the SLA must be associated with the account or not. true is for associating and false is for dissociating.

POST /api/v1/accounts/{account_id}/sla/{sla_id}

OAuth Scope

Desk.contacts.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/3263000000074571/sla/32630000000570017
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "associate" : true
}'

Response Example

Tasks

Tasks are work activities assigned to agents. It is not mandatory for tasks to be related to only ticket resolution.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the task

~~customFields~~

deprecated

list

User-defined fields related to the task

list

User-defined fields related to the task

departmentId
see documentation

long

ID of the department in which the task must be created

subject

string

Subject of the task

ticketId
see documentation

long

ID of the ticket with which the task must be associated

dueDate

timestamp

Due date for completing the task

ownerId

long

ID of the user to whom the task is assigned

category

string

Category of the task

status

string

Status of task completion

priority

string

Priority of the task

description

string

Description of the task

createdTime

timestamp

Time when the task was created

modifiedTime

timestamp

Time when the task was modified

creatorId

string

ID of the user who created the task

ticket

Ticket

Ticket associated with the task

contactId

long

ID of the contact associated with the task

reminder

show Attributes

JSONArray

Details of the reminder set for the task

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "cf" : { }, "reminder" : [ { "alertType" : [ "EMAIL" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T10:32:11.000Z" }, { "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T16:32:11.000Z" }, { "relativeReminderInMin" : "10", "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "RELATIVE" } ], "subject" : "New Task", "completedTime" : null, "departmentId" : "3000000007043", "dueDate" : "2016-07-29T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "createdTime" : "2016-07-26T17:32:11.000Z", "modifiedBy" : { "firstName" : "George", "lastName" : "McKinson", "photoURL" : null, "id" : "5000000015911" }, "id" : "3000000018001", "isSpam" : false, "category" : null, "ticketId" : "3000000008753", "status" : "Not Started" }

Get task

This API fetches a task from your help desk portal.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams.

GET /api/v1/tasks/{task_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/5000000074002?include=assignee,tickets,contacts,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TaskAPI task = ZDesk.getTaskAPIInstance(mailId);
Task response = task.getTask( taskId, include );

Response Example

{
  "modifiedTime" : "2019-04-08T07:26:26.000Z",
  "cf" : {
  },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : null,
    "id" : "5000000016294",
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open"
  },
  "reminder" : [ {
    "alertType" : [ "EMAIL", "SMS", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-24T04:52:13.000Z"
  } ],
  "contactId" : "5000000016252",
  "subject" : "New gadget replacement with latest OS",
  "completedTime" : null,
  "departmentId" : "5000000012710",
  "dueDate" : "2019-04-25T16:52:11.000Z",
  "creatorId" : "5000000015911",
  "description" : "Latest OS Version 32.9.4 ",
  "team" : null,
  "ownerId" : "5000000015911",
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e4d4dad33a9adf3649",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false
  },
  "createdTime" : "2019-04-08T07:26:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000074002",
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "category" : null,
  "ticketId" : "5000000016294",
  "status" : "Deferred"
}

List tasks

This API fetches a particular number of tasks, based on the limit specified.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams,projects.

from

integer

optional

Index number, starting from which the tasks must be fetched

limit

integer

optional,
range : 1-100

Number of tasks to list

departmentId
see documentation

long

optional

ID of the department from which the tasks must be fetched

departmentIds
see documentation

long

optional

Departments from which the tasks need to be queried

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

dueDate

string

optional,
max chars : 100

Due date for completing the task. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

isCompleted

boolean

optional

Key that denotes whether the task is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the tasks by a specific attribute: dueDate or createdTime.The default sorting order is ascending. A - prefix denotes a descending order of sorting.

GET /api/v1/tasks

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks?departmentId=5000000012710&include=teams,tickets,contacts,assignee
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TaskAPI task = ZDesk.getTaskAPIInstance(mailId);
GetTasksFilter filter = new GetTasksFilter.Builder().setViewId(viewId).build();
List<Task> response = task.getTasks( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticket" : null,
    "contactId" : null,
    "subject" : "Iphone charger replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000067003",
    "priority" : "Normal",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/d4c0a5dce55dcf20279262cd8594cd0d",
    "contact" : null,
    "createdTime" : "2019-04-30T14:21:50.000Z",
    "startTime" : "1970-01-01T00:00:00.000Z",
    "id" : "5000000209940",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "36",
      "photoURL" : null,
      "id" : "5000000067003"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : null,
    "status" : "Not Started",
    "direction" : "inbound"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : null,
    "subject" : "Tempered glass replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e46474bbeb6432292e",
    "contact" : null,
    "createdTime" : "2019-04-09T04:37:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000075033",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred12546",
    "direction" : "inbound"
  } ]
}

Create task

This API creates a task in your help desk portal.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the task

list

optional

User-defined fields related to the task

departmentId
see documentation

long

required

ID of the department in which the task must be created

subject

string

required,
max chars : 300

Subject of the task

ticketId
see documentation

long

optional

ID of the ticket with which the task must be associated

dueDate

timestamp

optional

Due date for completing the task

ownerId

long

optional

ID of the user to whom the task is assigned

category

string

optional,
max chars : 120

Category of the task

status

string

optional,
max chars : 120

Status of task completion

priority

string

optional,
max chars : 120

Priority of the task

description

string

optional,
max chars : 65535

Description of the task

contactId

long

optional

ID of the contact associated with the task

reminder

JSONArray

optional

Details of the reminder set for the task

POST /api/v1/tasks

OAuth Scope

Desk.activities.CREATE , Desk.activities.tasks.CREATE , ~~Desk.tasks.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "subject" : "Bug Fix #120", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "priority" : "High", "category" : null, "status" : "In Progress" }'

TaskAPI task = ZDesk.getTaskAPIInstance(mailId);
Task taskObj = new Task();
taskObj.setSubject(subject);
taskObj.setReminderType(reminderType);
taskObj.setDescription(description);
Task response = task.createTask( taskObj );

Response Example

{
  "modifiedTime" : "2016-07-14T09:14:41.000Z",
  "cf" : {
  },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Update task

This API helps update the details of a task.

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the task

list

optional

User-defined fields related to the task

departmentId
see documentation

long

optional

ID of the department in which the task must be created

subject

string

optional,
max chars : 300

Subject of the task

ticketId
see documentation

long

optional

ID of the ticket with which the task must be associated

dueDate

timestamp

optional

Due date for completing the task

ownerId

long

optional

ID of the user to whom the task is assigned

category

string

optional,
max chars : 120

Category of the task

status

string

optional,
max chars : 120

Status of task completion

priority

string

optional,
max chars : 120

Priority of the task

description

string

optional,
max chars : 65535

Description of the task

contactId

long

optional

ID of the contact associated with the task

reminder

JSONArray

optional

Details of the reminder set for the task

PATCH /api/v1/tasks/{task_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/3000000054002
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "subject" : "Bug Fix #120", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "category" : null, "priority" : "High", "status" : "In Progress" }'

Response Example

{
  "modifiedTime" : "2016-07-14T09:14:41.000Z",
  "cf" : {
  },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

List tasks by ticket

This API lists all tasks associated with a particular ticket.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the tasks must be fetched

isCompleted

boolean

optional

Key that denotes whether the task is completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam tasks or not

limit

integer

optional,
range : 1-100

Number of tasks to list

sortBy

string

optional,
max chars : 100

Key that sorts the tasks by a specific attribute: dueDate or createdTime.The default sorting order is ascending. A - prefix denotes a descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams,projects.

GET /api/v1/tickets/{ticket_id}/tasks

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tickets.READ~~ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/tasks?include=assignee,tickets,contacts,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TaskAPI task = ZDesk.getTaskAPIInstance(mailId);
GetTasksByTicketFilter filter = new GetTasksByTicketFilter.Builder().setIsCompleted(isCompleted).build();
List<Task> response = task.getTasksByTicket( ticketId, from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "subject" : "New gadget replacement with latest OS",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4d4dad33a9adf3649",
    "isCommented" : false,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-08T07:26:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000074002",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013466",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e4d4dad33a9adf3649",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred"
  }, {
    "subject" : "Tempered glass replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e46474bbeb6432292e",
    "isCommented" : false,
    "contact" : null,
    "createdTime" : "2019-04-09T04:37:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000075033",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : null,
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013466",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e46474bbeb6432292e",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred12546"
  } ]
}

List all tasks count

This API returns the number of tasks in your help desk.

Query Params

Param Name

Data Type

Description

viewId

long

required

ID of the view to apply while fetching the resources

departmentId
see documentation

long

required

ID of the department from which the task count must be fetched

assignee

string

optional,
max chars : 100

Key that filters tasks by assignee. A valid assigneeId must be passed for this parameter. Multiple assigneeIds can be passed as comma-separated values.

dueDate

string

optional,
max chars : 100

Filter by task duedate. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today. You can include both values by separating them with a comma

GET /api/v1/tasks/count

OAuth Scope

Desk.tasks.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/count?viewId=5000000007880&departmentId=5000000007069
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

Update many tasks

This API updates multiple tasks at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/tasks/updateMany

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "mobile", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "8508569875" }'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Products

Products are the goods/services your organization sells.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the product

departmentIds
see documentation

list

IDs of departments associated with the product

ownerId

long

ID of user to whom the product is assigned

productName

string

Name of the product

productCode

string

Reference code of the product

productCategory

string

Category to which the product belongs

manufacturer

string

Organization that manufactures the product

unitPrice

double

Price of the product

~~customFields~~

deprecated

list

User-defined fields related to the product

list

User-defined fields related to the product

createdBy

long

User who added the product to the help desk portal

modifiedBy

long

User who modified the details of the product

createdTime

timestamp

Time of adding the product to the help desk portal

modifiedTime

timestamp

Time of modifying product details

description

string

Description of the product

Example

{ "unitPrice" : "100.0", "modifiedTime" : "2016-06-27T06:33:19.000Z", "productCode" : "E7450", "createdBy" : "4000000008692", "module" : "products", "createdTime" : "2016-06-27T06:33:19.000Z", "description" : "New Product", "modifiedBy" : "4000000008692", "id" : "4000000013043", "departmentIds" : [ "6000000007239", "6000000029263" ], "productName" : "DELL" }

Get product

This API fetches a single product from your helpdesk.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Key that fetches secondary information related to the product. Values allowed are: departments and owner. You can pass multiple values by separating them with commas.

GET /api/v1/products/{product_id}

OAuth Scope

Desk.products.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/6000000124009
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
Product response = product.getProduct( productId, include );

Response Example

{
  "owner" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/6000000009050/photo?orgId=581861259",
    "firstName" : "Aaron",
    "lastName" : "Stone",
    "name" : "Aaron Stone",
    "id" : "6000000009050"
  },
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-06-28T13:25:06.000Z",
  "cf" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000009450", "6000000009380", "6000000009230" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009",
  "departments" : [ {
    "name" : "Associated Department 1",
    "id" : "6000000009450"
  }, {
    "name" : "Associated Department 2",
    "id" : "6000000009380"
  }, {
    "name" : "Associated Department 3",
    "id" : "6000000009230"
  } ]
}

List products

This API lists a specific number of products from your help desk portal, based on the limit defined. (Note: The departmentIds key will soon be deprecated and not included in API responses.)

Query Params

Param Name

Data Type

Description

viewId

long

optional

ID of the view to apply while fetching the products

from

integer

optional

Index number, starting from which the products must be fetched

limit

integer

optional,
range : 1-100

No. of products to fetch

~~departmentIds~~

deprecated

long

optional

This key will soon be deprecated from both API requests and responses. Please replace it with the departmentId key in your code.

departmentId

long

optional

ID of the department from which the products must be fetched. If you want to list the products configured in all accessible departments, pass the value 0.

ownerId

long

optional

ID of user to whom the product is assigned

sortBy

string

optional,
max chars : 100

Sort by a specific attribute : productName, productCode, unitPrice, createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: layoutId. Maximum of 30 fields is supported as comma separated values.

include
see documentation

list

optional

Secondary information related to the contact.Value supported is owner.

GET /api/v1/products

OAuth Scope

Desk.products.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products?departmentIds=6000000007239,6000000029263
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
GetProductsFilter filter = new GetProductsFilter.Builder().setViewId(viewId).build();
List<Product> response = product.getProducts( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121033",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "HTC"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121037",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "Dell"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000145024",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "Lenovo"
  } ]
}

Create product

This API adds a product to your helpdesk.

Attributes

Param Name

Data Type

Description

departmentIds
see documentation

list

required

IDs of departments associated with the product

ownerId

long

optional

ID of user to whom the product is assigned

productName

string

required,
max chars : 200

Name of the product

productCode

string

optional,
max chars : 200

Reference code of the product

productCategory

string

optional,
max chars : 200

Category to which the product belongs

manufacturer

string

optional,
max chars : 200

Organization that manufactures the product

unitPrice

double

optional

Price of the product

~~customFields~~

deprecated

list

optional

User-defined fields related to the product

list

optional

User-defined fields related to the product

description

string

optional,
max chars : 65535

Description of the product

POST /api/v1/products

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/products
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "unitPrice" : "100",
  "productCode" : "12345",
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "productName" : "Dell"
}'

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
Product productObj = new Product();
productObj.setUnitPrice(unitPrice);
productObj.setProductCode(productCode);
productObj.setDescription(description);
productObj.setProductName(productName);
Product response = product.createProduct( productObj );

Response Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-07-18T10:46:25.667Z",
  "cf" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-07-18T10:46:25.667Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000164001"
}

List tickets by products

This API lists tickets received from a specific products.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

GET /api/v1/products/{product_id}/tickets

OAuth Scope

Desk.settings.READ , Desk.search.READ , Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/18944000000424033/tickets?include=departments,team,assignee
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsByProductFilter filter = new GetTicketsByProductFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTicketsByProduct( productId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "sentiment" : "NEGATIVE",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zohodesk.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "status" : "Open"
  } ]
}

Update product

This API updates details of a product in your help desk portal.

Attributes

Param Name

Data Type

Description

departmentIds
see documentation

list

optional

IDs of departments associated with the product

ownerId

long

optional

ID of user to whom the product is assigned

productName

string

optional,
max chars : 200

Name of the product

productCode

string

optional,
max chars : 200

Reference code of the product

productCategory

string

optional,
max chars : 200

Category to which the product belongs

manufacturer

string

optional,
max chars : 200

Organization that manufactures the product

unitPrice

double

optional

Price of the product

~~customFields~~

deprecated

list

optional

User-defined fields related to the product

list

optional

User-defined fields related to the product

description

string

optional,
max chars : 65535

Description of the product

PATCH /api/v1/products/{product_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/products/6000000124009
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "departmentIds" : [ "6000000029263", "6000000125041" ],
  "productName" : "Dell"
}'

Response Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-07-18T10:53:40.787Z",
  "cf" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000029263", "6000000125041" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009"
}

Move Products to trash

This API moves products to the Recycle Bin of your help desk portal.

Attributes

Param Name

Data Type

Description

departmentId
see documentation

long

optional

ID of the department containing the products

productIds

list

required

IDs of the products you want to delete

POST /api/v1/products/moveToTrash

OAuth Scope

Desk.products.DELETE , ~~Desk.settings.DELETE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/products/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "productIds" : [ "2000032003232" ],
  "departmentId" : "2000032006800"
}'

ProductAPI product = ZDesk.getProductAPIInstance(mailId);
boolean response = product.moveToTrash( productIds );

Response Example

Search for duplicate records

This API searches for duplicate records of a product.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the products must be fetched

limit

integer

optional,
range : 1-100

No. of products to fetch

productName

string

required,
max chars : 200

Name of the product, used as the keyword for the search

GET /api/v1/products/searchDuplicates

OAuth Scope

Desk.products.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/searchDuplicates?productName=Dell
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121033",
    "productName" : "Dell"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121037",
    "productName" : "Dell"
  } ]
}

Associate contacts with a product

This API associates contacts with a product.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of the resources to associate

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/products/{product_id}/associateContacts

OAuth Scope

Desk.products.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/products/2000000031001/associateContacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "2000000034031", "2000000034029" ],
  "associate" : true
}'

Response Example

Associate accounts with a product

This API associates accounts with a product.

Attributes

Param Name

Data Type

Description

ids

list

required

IDs of the resources to associate

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/products/{product_id}/associateAccounts

OAuth Scope

Desk.products.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/products/2000000031001/associateAccounts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "2000000029035", "2000000029001" ],
  "associate" : true
}'

Response Example

List accounts associated with product

This API lists the accounts associated with a product

Query Params

Param Name

Data Type

Description

from

int

optional

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

sortBy

string

optional,
max chars : 100

Key that sorts the accounts by a specific attribute: accountName or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting

GET api/v1/products/{products_id}/accounts

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://support.zoho.com/api/v1/products/2000000031001/accounts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId);
List<Account> response = account.getAccountsUnderProduct( productId, from, limit, sortBy, isAscending );

Response Example

{
  "data" : [ {
    "website" : "112121",
    "accountName" : "Admin Account",
    "phone" : "121212",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "id" : "1892000000052077",
    "email" : "admin@zylker.com"
  }, {
    "website" : "1211212",
    "accountName" : "Agent Account",
    "phone" : "11211",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

List contacts associated with product

This API lists the contacts associated with a product.

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which the contacts must be listed

limit

integer

optional,
range : 1-100

Number of contacts to fetch

sortBy

string

optional,
max chars : 100

Parameter that sorts contacts by one of these attributes:
firstName,

lastName,

phone,

email,

account,

createdTime,

modifiedTime

include
see documentation

list

optional

Key that fetches secondary information related to the contact.Value allowed is accounts

isSpam

boolean

optional,
default : false

Filters Spam contacts

GET api/v1/products/{products_id}/contacts

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://support.zoho.com/api/v1/products/2000000031001/contacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ContactAPI contact = ZDesk.getContactAPIInstance(mailId);
GetContactsUnderProductFilter filter = new GetContactsUnderProductFilter.Builder().setIsSpam(isSpam).build();
List<Contact> response = contact.getContactsUnderProduct( productId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : true,
    "phone" : "555555",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : true,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

HelpCenter

Help center refers to the central self-service portal through which customers can look for solutions and fix issues by themselves.The help center brings together different help modules, such as your knowledge base, community forum, live chat, and ticket submission form

Example

{ "domains" : [ { "name" : "help.zoho.com", "type" : "PRIMARY" }, { "name" : "forums.zoho.com", "type" : "SECONDARY" } ], "logoLinkBackUrl" : "https://zoho.com/desk", "departmentIds" : [ "24073000002576907", "24073000002577809" ], "isMultilingualEnabled" : true, "logoUrl" : "https://desk.zoho.com/api/v1/helpCenter/24073000002579275/logo/240730000025738740?orgId=2389290", "url" : "https://help.zoho.com/portal", "locales" : [ "en" ], "isDefault" : true, "siteMapUpdatedTime" : "2019-05-30T21:34:01.000Z", "name" : "restapiautomatiion", "favIconUrl" : "https://desk.zoho.com/api/v1/helpCenter/24073000002579275/favIcon/240730000025783905?orgId=2389290", "id" : "59882000000170069", "helpCenterLocales" : [ { "name" : "ZohoCorp Portal", "locale" : "en", "type" : "DEFAULT", "status" : "ACCESIBLE_IN_HELPCENTER" } ], "primaryLocale" : "en_US", "status" : "ACTIVE" }

List help centers

This API lists the help centers configured in your Zoho Desk portal.

GET /api/v1/helpCenters

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/helpCenters?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

HelpcenterAPI helpcenter = ZDesk.getHelpcenterAPIInstance(mailId);
List<Helpcenter> response = helpcenter.getAllHelpCenters( );

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "name" : "Zoho Cares",
    "id" : "24073000002579275",
    "departmentIds" : [ "24073000000102043" ],
    "isMultilingualEnabled" : true,
    "helpCenterLocales" : [ {
      "name" : "ZohoCorp Portal",
      "locale" : "en",
      "type" : "DEFAULT",
      "status" : "ACCESIBLE_IN_HELPCENTER"
    } ],
    "primaryLocale" : "en",
    "logoUrl" : "https://localimg.zohostatic.com/support/app/images/portalLogo.de847024ebc0131731a3.png",
    "url" : "https://help.zoho.com/portal/",
    "status" : "ACTIVE"
  } ]
}

Get details of help center

This API fetches the details of a particular help center.

GET /api/v1/helpCenters/{helpcenter_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/helpCenters/24073000002579275?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

HelpcenterAPI helpcenter = ZDesk.getHelpcenterAPIInstance(mailId);
Helpcenter response = helpcenter.getHelpCenter( helpcenterId );

Response Example

{
  "domains" : [ {
    "name" : "forums.zoho.com",
    "type" : "SECONDARY"
  }, {
    "name" : "help.zoho.com",
    "type" : "PRIMARY"
  } ],
  "logoLinkBackUrl" : "https://www.zoho.com/desk/",
  "departmentIds" : [ "24073000000102043" ],
  "logoUrl" : "https://localimg.zohostatic.com/support/app/images/portalLogo.de847024ebc0131731a3.png",
  "url" : "https://help.zoho.com/portal/",
  "isDefault" : true,
  "siteMapUpdatedTime" : "2019-12-26T08:48:09.000Z",
  "name" : "Zoho Cares",
  "favIconUrl" : "https://localimg.zohostatic.com/support/app/images/support-2.befdbf2e5043b988ef7e.ico",
  "id" : "24073000002579275",
  "helpCenterLocales" : [ {
    "name" : "Zoho Cares",
    "locale" : "en",
    "type" : "DEFAULT",
    "status" : "ACCESIBLE_IN_HELPCENTER"
  } ],
  "primaryLocale" : "en",
  "status" : "ACTIVE"
}

Update Helpcenter sitemaps

This API will generate sitemaps for the given Helpcenter

POST /api/v1/helpCenters/4000000190032/sitemaps

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/helpCenters/4000000190032/sitemaps?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Users

Users are the end-users of your product/service, who access your help center to find solutions.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the user

show Attributes

list

Email address of the user

status

string

Activation status of the user. Values supported are ACTIVE and DISABLED.

Example

{ "id" : "142456352454", "email" : [ { "emailAddress" : "zylcare@zoho.com", "isVerified" : "true", "isPrimary" : "true" } ] }

List help center users

This API lists a particular number of help center users, based on the limit defined. It also helps you search for specific users.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-50

Number of users to list. The default value and the maximum value allowed is 50.

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

sortBy

String

optional

Key that sorts the list of users by a particular attribute: -(email or modifiedTime)

status

String

optional

Activation status of the users to list

helpCenterId

long

optional

ID of the help center from which the users must be fetched

include
see documentation

string

optional,
max chars : 100

Additional information related to the user. Value allowed is count.

GET /api/v1/users

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~ , ~~Desk.basic.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&include=count
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
    "emailAddress" : "dev.zoho@zohocorp.com",
    "name" : "Developer",
    "id" : "310975130121",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#39B54A",
        "textColor" : "#FFFFFF"
      },
      "name" : "Lock Label",
      "id" : "24073000002823026",
      "logoUrl" : null
    },
    "type" : "ENDUSER",
    "status" : "ACTIVE"
  } ],
  "count" : "1"
}

Get details of user

This API fetches the details of a particular help center user.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the user. Value allowed is contact.

GET /api/v1/users/{user_id}

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~ , ~~Desk.basic.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/users/310975130121?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
  "contactId" : "3313135931139",
  "contact" : {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "name" : "Developer",
    "id" : "3313135931139"
  },
  "name" : "Developer",
  "id" : "310975130121",
  "label" : {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "name" : "Lock Label",
    "id" : "24073000002823026",
    "logoUrl" : null
  },
  "type" : "ENDUSER",
  "email" : [ {
    "emailAddress" : "zylcare@zoho.com",
    "isVerified" : "false",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}

Update details of user

This API helps update the details of a particular help center user.

Query Params

Param Name

Data Type

Description

helpCenterId

long

optional

ID of the help center from which the user must be updated

Attributes

Param Name

Data Type

Description

list

optional

Email ID of the user

status

string

optional,
max chars : 100

Activation status of the user. Values supported are ACTIVE and DISABLED.

PATCH /api/v1/users/{user_id}

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/users/4000000190069?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "email" : [ {
    "emailAddress" : "zylcare@zoho.com",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}'

Response Example

{
  "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
  "contactId" : "3313135931139",
  "name" : "Developer",
  "id" : "310975130121",
  "label" : {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "name" : "Lock Label",
    "id" : "24073000002823026",
    "logoUrl" : null
  },
  "type" : "ENDUSER",
  "email" : [ {
    "emailAddress" : "zylcare@zoho.com",
    "isVerified" : "false",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}

Anonymize user

This API permanently deletes all identifying information about a user from your help center.

Attributes

Param Name

Data Type

Description

anonymizedName

string

optional,
max chars : 100

Display name of the user in tickets and community topics after anonymization

POST api/v1/users/{user_id}/anonymize

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/users/4000000190069?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "anonymizedName" : "Guest User 001"
}'

Response Example

List user groups

This API lists a particular number of user groups in a help center, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the groups must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of groups to list. The default value and the maximum value allowed is 50

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

sortBy

String

optional

Key that sorts the list of user groups by a particular attribute: -(addedTime)

helpCenterId

long

optional

ID of the help center from which the groups must be fetched

GET /api/v1/users/{user_id}/groups

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/users/24073000002913021/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "addedTime" : "2020-04-06T04:50:50.000Z",
    "name" : "Zoho CRM Partners",
    "id" : "24073000002957057",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : null,
    "status" : "ACTIVE"
  }, {
    "addedTime" : "2020-04-06T04:50:30.000Z",
    "name" : "Zoho Desk Partners",
    "id" : "24073000002957051",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/24073000002959001?portalId=b363e6f8e029247a38a55e49806bf1f683801f9cd92870bf7cc50d48844902f0",
    "status" : "ACTIVE"
  }, {
    "addedTime" : "2020-04-06T04:50:14.000Z",
    "name" : "Zoho One Prime Customers",
    "id" : "24073000002957045",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : null,
    "status" : "ACTIVE"
  } ]
}

Add user to groups

This API adds a user to the groups specified.

Query Params

Param Name

Data Type

Description

helpCenterId

long

optional

ID of the help center from which the groups must be validated

Attributes

Param Name

Data Type

Description

groups

list

required

IDs of the groups to which the user must be added

POST /api/v1/users/{user_id}/groups/associate

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/groups/associate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "groups" : [ {
    "id" : "24073000002723212"
  }, {
    "id" : "24073000002732252"
  }, {
    "id" : "24073000002957051"
  }, {
    "id" : "24073000002793019"
  } ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002957051",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002793019",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : false,
    "id" : "24073000002723212",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : false,
    "id" : "24073000002732252",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

Remove user from groups

This API removes a user from the groups specified.

Query Params

Param Name

Data Type

Description

helpCenterId

long

optional

ID of the help center from which the groups must be removed

Attributes

Param Name

Data Type

Description

groupIds

list

required

IDs of the groups from which the user must be removed

POST /api/v1/users/{user_id}/groups/dissociate

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/groups/dissociate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "groupIds" : [ "24073000002957051", "24073000002932512", "24073000002953232" ]
}'

Response Example

{
  "results" : [ {
    "success" : false,
    "id" : "24073000002957051",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Minimum user should be maintained"
    }
  }, {
    "success" : false,
    "id" : "24073000002932512",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : true,
    "id" : "24073000002953232",
    "errors" : null
  } ]
}

List labels of user

This API lists a particular number of labels associated with a user, based on the limit defined.

Query Params

Param Name

Data Type

Description

isPrimary

boolean

optional

Key that filters the primary label assigned to the user

from

int

optional,
default : 1,
range : >0

Index number, starting from which the labels must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of labels to list. The default value and the maximum value allowed is 50

sortBy

String

optional

Key that sorts the list of labels by a particular attribute: -(assignedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

helpCenterId

long

optional

ID of the help center from which the labels must be fetched

GET /api/v1/users/{user_id}/labels

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/users/24073000002913021/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "preferences" : {
      "shape" : "ROUNDED",
      "bgColor" : "#5787E0",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "Prime Customer",
    "id" : "24073000002958013",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  }, {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "Zoho One",
    "id" : "24073000002958023",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  }, {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#CE6785",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "MVP",
    "id" : "24073000002958029",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  } ]
}

Assign labels to user

This API assigns the labels you specify to a particular user.

Query Params

Param Name

Data Type

Description

helpCenterId

long

optional

ID of the help center from which the labels must be validated

Attributes

Param Name

Data Type

Description

labels

list

required

List containing the details of the labels to assign

POST /api/v1/users/{user_id}/labels/assign

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/labels/assign?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "labels" : [ {
    "isPrimary" : "false",
    "id" : "24073000002958013"
  }, {
    "isPrimary" : "true",
    "id" : "24073000002152013"
  }, {
    "isPrimary" : "false",
    "id" : "24073000002958023"
  } ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002958013",
    "errors" : null
  }, {
    "success" : true,
    "id" : "24073000002958023",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002152013",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

Remove labels from user

This API removes the labels you specify from a particular user.

Query Params

Param Name

Data Type

Description

helpCenterId

long

optional

ID of the help center from which the labels must be removed

Attributes

Param Name

Data Type

Description

labelIds

list

required

List containing the IDs of the labels to remove

POST /api/v1/users/{user_id}/labels/remove

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/labels/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "labelIds" : [ "24073000002958023", "24073000002952323" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002958023",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002952323",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

Labels

Labels are tags that you add to users to highlight their contribution in your help center.

Example

{ }

Create label

This API creates a label in your help center.

Attributes

Param Name

Data Type

Description

name

String

required

Name of the label

logoId

long

optional

ID of the logo set for the label

helpCenterId

long

required

ID of the help center in which the label must be created

preferences

JSONObject

optional

Visual preferences related to the label/logo

POST /api/v1/labels

OAuth Scope

Desk.contacts.CREATE , ~~Desk.settings.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "preferences" : { "shape" : "ROUNDED", "bgColor" : "#FFEE", "textColor" : "#FFEE" }, "name" : "Pro Customer", "helpCenterId" : "310975130119", "logoId" : "310975130121" }'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "0",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

Update label

This API helps update the details of a label.

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the label

logoId

long

optional

ID of the logo set for the label

preferences

JSONObject

optional

Visual preferences related to the label/logo

PATCH /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "preferences" : { "shape" : "ROUNDED", "bgColor" : "#FFEE", "textColor" : "#FFEE" }, "name" : "Pro Customer", "logoId" : "310975130121" }'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "892",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

Get details of label

This API fetches the details of a particular label.

GET /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "320",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

List labels

This API lists a particular number of labels, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the labels must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-50

Number of labels to list. The default value and the maximum value allowed is 50.

sortBy

String

optional

Key that sorts the list of labels by a particular attribute: -(createdTime or modifiedTime, or name)

searchBy

String

optional

Search keyword to use for finding a particular label. The keyword must contain at least two characters. Three types of search are supported: keyword* (search for values that start with the keyword, *keyword* (search for values that contain the keyword), and keyword (search for values that are exact matches of the keyword)

helpCenterId

long

optional

ID of the help center from which the labels must be fetched

GET /api/v1/labels

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-09-19T04:58:50.000Z",
    "preferences" : {
      "shape" : "ROUNDED",
      "bgColor" : "#FFEE",
      "textColor" : "#FFEE"
    },
    "creator" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "modifier" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "name" : "Pro Customer",
    "count" : "892",
    "createdTime" : "2017-09-19T04:58:50.000Z",
    "id" : "310975130110",
    "helpCenterId" : "310975130119",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
  } ]
}

Delete label

This API deletes a label from your help center.

DELETE /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.DELETE , ~~Desk.settings.DELETE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Delete label by labelIds

This API deletes labels, based on the IDs specified.

Query Params

Param Name

Data Type

Description

labelIds

long

optional

IDs of the labels to delete

DELETE /api/v1/labels

OAuth Scope

Desk.contacts.DELETE , ~~Desk.settings.DELETE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&labelIds=310975130110,310975130021
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Assign label to users

This API assigns a particular label to multiple users.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users to whom the label must be assigned

POST /api/v1/labels/{label_id}/users/add

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/labels/310975130110/users/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3109751143253", "310975131231", "310975133141", "310975101849" ]
}'

Response Example

Remove users under a label

This API removes all users under a particular label.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users from whom the label must be removed

POST /api/v1/labels/{label_id}/users/remove

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/labels/310975130110/users/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3109751143253", "310975131231", "310975133141", "310975101849" ]
}'

Response Example

List users under a label

This API lists a particular number of users under a label, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-100

Number of users to list. The default value is 50 and the maximum value allowed is 100

sortBy

String

optional

Key that sorts the list of users by a specific attribute: -(assignedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

GET /api/v1/labels/{label_id}/users

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/labels/310975130110/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : null,
    "emailAddress" : "zykler.rm@zohocorp.com",
    "name" : "svega RM",
    "userType" : "ENDUSER",
    "assignee" : {
      "photoUrl" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "Chris",
      "id" : "6000000015895"
    },
    "id" : "6000000032907",
    "assignedTime" : "2019-08-09T07:47:44.000Z",
    "status" : "ACTIVE"
  } ]
}

Groups

Groups are collections of end-users—often related to a specific account, geography, brand, or product—using which you can determine access to your knowledge base and community forums.

Example

{ }

Create user groups

This API creates a user group in your help center.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 100

Name of the group

description

string

optional,
max chars : 3000

A brief description of the group

logoId

long

optional

ID of the logo to associate with the group

helpCenterId

long

required

ID of the help center in which the group must be created

POST /api/v1/groups

OAuth Scope

Desk.contacts.CREATE , ~~Desk.settings.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Prime Customer", "description" : "Prime customer will have special access to Knowledge base module and Community categories", "helpCenterId" : "31097519102", "logoId" : "310975130121" }'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Prime Customer",
  "count" : "0",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "31097519102",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

Update group

This API helps update the details of a user group.

Attributes

Param Name

Data Type

Description

name

string

optional,
max chars : 100

Name of the group

description

string

optional,
max chars : 3000

A brief description of the group

logoId

long

optional

ID of the logo to associate with the group

PATCH /api/v1/groups/{group_Id}

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/groups/310975134902?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "MVP Customer", "description" : "Prime customer will have special access to Knowledge base module and Community categories", "logoId" : "310975130133", "status" : "ACTIVE" }'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "MVP Customer",
  "count" : "892",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "31097519102",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

Get details of group

This API fetches the details of a particular user group.

GET /api/v1/groups/{group_id}

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groups/310975134902?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "MVP Customer",
  "count" : "892",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

List groups

This API lists a particular number of groups, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the groups must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-50

Number of groups to list. The default value and the maximum value allowed is 50.

sortBy

String

optional

Key that sorts the list of groups by a particular attribute: -(createdTime, modifiedTime, name, or count)

searchBy

String

optional

Search keyword to use for finding a particular group The keyword must contain at least two characters. Three types of search are supported: keyword* (search for values that start with the keyword, *keyword* (search for values that contain the keyword), and keyword (search for values that are exact matches of the keyword).

helpCenterId

long

optional

ID of the help center from which the resource must be fetched

GET /api/v1/groups

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=310975130119
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-09-19T04:58:50.000Z",
    "creator" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "modifier" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "name" : "Pro Customer",
    "count" : "353",
    "description" : "Pro Customers paid customers of the org will avail 24x7 Support service",
    "createdTime" : "2017-09-19T04:58:50.000Z",
    "id" : "310975130110",
    "helpCenterId" : "310975130119",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
    "status" : "ACTIVE"
  } ]
}

Delete group

This API deletes a user group from your help center.

DELETE /api/v1/groups/{group_Id}

OAuth Scope

Desk.contacts.DELETE , ~~Desk.settings.DELETE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/groups/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Add users to group

This API adds users to a particular group.

Attributes

Param Name

Data Type

Description

users

list

required

IDs of the users who must be added to the group

POST /api/v1/groups/{group_id}/users/add

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/groups/310975130110/users/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "users" : [ {
    "id" : "17883000000094001"
  }, {
    "id" : "17883000000094023"
  } ]
}'

Response Example

Remove users from group

This API removes particular users from a group.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users who must be removed from the group

POST /api/v1/groups/{group_Id}/users/remove

OAuth Scope

Desk.contacts.UPDATE , ~~Desk.settings.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/groups/310975130110/users/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "17883000000013101", "17883000000094023" ]
}'

Response Example

List users in a group

This API lists a particular number of users in a group, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-100

Number of users to list. The default value is 50 and the maximum value allowed is 100.

sortBy

String

optional

Key that sorts the list of users, based on a specific attribute: -(addedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

GET /api/v1/groups/{group_Id}/users

OAuth Scope

Desk.contacts.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groups/310975130110/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : null,
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/portal/api/user/24073000000095005/photo?orgId=143315",
      "name" : "ZylCare Admin",
      "id" : "24073000000095005"
    },
    "emailAddress" : "zykler.k@zohocorp.com",
    "name" : "John ",
    "addedTime" : "2019-11-08T14:57:39.000Z",
    "userType" : "ENDUSER",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#6CD4DF",
        "textColor" : "#FFFFFF"
      },
      "name" : "Prime Customer",
      "id" : "24073000002132001"
    },
    "id" : "24073000001997453",
    "status" : "ACTIVE"
  } ]
}

Articles

Articles are pieces of help content that you share on the knowledge base of your help desk portal. Articles intend to educate users on how to use features/functions and provide solutions to issues that customers frequently encounter.

ATTRIBUTES

Attribute Name

Data Type

Description

Long

ID of the article

departmentId

Long

ID of the department associated with the article

categoryId

Long

ID of the category associated with the article

title

String

Title of the article

answer

String

Content of the article

permalink

String

The permalink to access the article

authorId

Long

ID of the user who created the article

status

String

Publishing status of the article. Values allowed are
Draft,

Published,

Review

permission

String

Access permissions for the article. Values allowed are
ALL,

REGISTEREDUSERS,

AGENTS

tags

String Array

Tags associated with the article

seoTitle

String

SEO-specific title of the article

seoKeywords

String

SEO-specific title of the article

seoDescription

String

SEO-specific title of the article

expiryDate

String

Date until which the article will appear in the knowledge base

Example

{ "modifiedTime" : "2017-09-13T18:44:11.000Z", "attachments" : [ { "reseourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40", "name" : "Attachment1.png", "viewUrl" : "https://desk.zoho.com/DocsDisplay?attachId=b34f0de640d72a1dc0f0b676f752dadae612657a51fd5fbe&action=view&zgId=3baf28131e9f8df2dc91a236738b3d70&entityId=b34f0de640d72a1d61ce88b268c6605542acf79f93f757e8", "downloadUrl" : "https://desk.zoho.com/DocsDisplay?attachId=b34f0de640d72a1dc0f0b676f752dadae612657a51fd5fbe&action=download&zgId=3baf28131e9f8df2dc91a236738b3d70&entityId=b34f0de640d72a1d61ce88b268c6605542acf79f93f757e8", "createdTime" : "2017-09-14T00:14:09.699Z", "filesize" : "113727" } ], "reviewedTime" : null, "departmentId" : "22372000000006907", "modifierId" : "7000000015932", "creatorId" : "7000000015932", "title" : "Importance of a Knowledge Base", "expiryDate" : "2018-05-21T05:55:00.000Z", "public" : true, "createdTime" : "2017-09-13T18:18:32.000Z", "modifiedBy" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828", "name" : "Zylker", "id" : "22372000000094005", "zuid" : "234543" }, "id" : "22372000000119001", "seo" : { "keywords" : "Knowledge base, Helpcenter", "description" : "Knowledge base for your product", "title" : "Knowledge base" }, "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.", "latestVersionStatus" : "Draft", "author" : { "photoURL" : null, "name" : "Zylker", "id" : "7000000015932", "zuid" : "234543" }, "permission" : "ALL", "reviewedBy" : null, "authorId" : "22372000000094005", "tags" : [ "helpcenter", "knowledge base" ], "commentCount" : "0", "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.", "latestVersion" : "0.1", "createdBy" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828", "name" : "Zylker", "id" : "22372000000094005", "zuid" : "234543" }, "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-a-knowledge-base", "latestPublishedVersion" : "null", "attachmentCount" : "1", "position" : "0", "metrics" : { "feedbackCount" : "0", "unlikeCount" : "0", "lastUsageTime" : null, "likeCount" : "0", "viewCount" : "0", "lastActivityTime" : "2017-09-13T18:44:11.000Z", "usageCount" : "0" }, "permalink" : "test123-13-9-2017", "category" : { "name" : "General", "id" : "22372000000094159" }, "categoryId" : "7000000016129", "status" : "Draft" }

List articles

This API fetches a specific number of articles from your knowledge base, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

optional,
range : >0

Index number starting from which the articles must be fetched.

limit

Integer

optional,
range : 1-50

Number of articles to fetch

sortBy

String

optional

Key that sorts the articles based on a specific attribute:
createdTime,
or
modifiedTime

permission

String

optional

Access permission for the article. Values allowed are: ALL, REGISTEREDUSERS, and AGENTS

authorId

Long

optional

ID of article owner

categoryId

Long

optional

ID of the category to which the article belongs

modifiedTimeRange

timestamp

optional

Key that filters articles modified within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

expiryTimeRange

timestamp

optional

Key that filters articles which will expire within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

status

String

optional

Publishing status of the article. Values allowed are Draft, Published, Review, Expired

GET /api/v1/articles

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles?from=0&limit=10&sortBy=-createdTime&status=Published&categoryId=4000000013240&permission=ALL&orgId=5686513&modifiedTimeRange=2018-07-16T04:48:08.000Z,2018-07-16T07:48:08.000Z&authorId=4000000012931
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-06-24T11:46:43.000Z",
    "creatorId" : "4000000000059",
    "dislikeCount" : "0",
    "modifierId" : "4000000000059",
    "likeCount" : "0",
    "locale" : "en",
    "ownerId" : "4000000000059",
    "title" : "Answering your first ticket.",
    "isTrashed" : false,
    "createdTime" : "2020-06-24T11:46:43.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019059",
    "viewCount" : "0",
    "owner" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
    "latestVersionStatus" : "Published",
    "myVote" : null,
    "author" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "permission" : "AGENTS",
    "authorId" : "4000000000059",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "4000000017276",
    "translationId" : "4000000017294",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "latestVersion" : "1.0",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "feedbackCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
    "attachmentCount" : "0",
    "latestPublishedVersion" : "1.0",
    "category" : {
      "name" : "General",
      "id" : "4000000017287",
      "locale" : "en"
    },
    "permalink" : "answering-your-first-ticket",
    "categoryId" : "4000000017287",
    "status" : "Published"
  } ]
}

Get article

This API fetches an article from your knowledge base.

Query Params

Param Name

Data Type

Description

version

String

optional

Version number of the article

GET /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000000133001?version=1.2&orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "likeCount" : "0",
  "locale" : "en",
  "ownerId" : "4000000000059",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "isTrashed" : false,
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019059",
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "latestVersionStatus" : "Published",
  "myVote" : null,
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "usageCount" : "0",
  "commentCount" : "0",
  "rootCategoryId" : "4000000017276",
  "tags" : [ "first ticket" ],
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "translationId" : "4000000017294",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "latestPublishedVersion" : "1.0",
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "permalink" : "answering-your-first-ticket",
  "categoryId" : "4000000017287",
  "status" : "Published"
}

Create an article

This API creates an article in your helpdesk.

Attributes

Param Name

Data Type

Description

categoryId

Long

required

The Category

title

String

required

The title of Solution

answer

String

required

The answer part of Solution

permalink

String

optional

The permalink of Solution

authorId

Long

optional

The owner of the solution

status

String

required

Status of the Solution

permission

String

required

Permission of the Solution

tags

String Array

optional

Tags associated with the Solution

seoTitle

String

optional

SEO Title of Solution

seoKeywords

String

optional

SEO Key of Solution

seoDescription

String

optional

SEO Description of Solution

expiryDate

String

optional

Schedule expiry date

POST /api/v1/articles

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "expiryDate" : "2018-05-21T05:55:00.000Z", "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.", "seoDescription" : "Knowledge Base for your product", "permission" : "ALL", "title" : "Importance of a Knowledge Base", "permalink" : "knowledgebase", "authorId" : 22372000000094004, "seoTitle" : "Knowledge Base", "seoKeywords" : "Helpcenter, Knowledge Base", "categoryId" : 22372000000094160, "status" : "Draft", "tags" : [ "knowledge base", "helpcenter" ] }'

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "likeCount" : "0",
  "locale" : "en",
  "ownerId" : "4000000000059",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "isTrashed" : false,
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019059",
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "latestVersionStatus" : "Published",
  "myVote" : null,
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "usageCount" : "0",
  "commentCount" : "0",
  "rootCategoryId" : "4000000017276",
  "tags" : [ "first ticket" ],
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "translationId" : "4000000017294",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "latestPublishedVersion" : "1.0",
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "permalink" : "answering-your-first-ticket",
  "categoryId" : "4000000017287",
  "status" : "Published"
}

Update an article

This API updates an existing article.

Query Params

Param Name

Data Type

Description

Attributes

Param Name

Data Type

Description

categoryId

Long

optional

The Category

title

String

optional

The title of Solution

answer

String

optional

The answer part of Solution

permalink

String

optional

The permalink of Solution

authorId

Long

optional

The owner of the solution

status

String

optional

Status of the Solution

permission

String

optional

Permission of the Solution

tags

String Array

optional

Tags associated with the Solution

seoTitle

String

optional

SEO Title of Solution

seoKeywords

String

optional

SEO Key of Solution

seoDescription

String

optional

SEO Description of Solution

expiryDate

String

optional

Schedule expiry date

PATCH /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/articles/22372000000133001?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "expiryDate" : "2018-05-21T05:55:00.000Z", "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.", "seoDescription" : "Knowledge base for your product", "permission" : "REGISTEREDUSERS", "title" : "Importance of a Knowledge Base", "authorId" : 22372000000094004, "seoTitle" : "Knowledge base", "seoKeywords" : "Knowledge base, Helpcenter", "categoryId" : 22372000000094160, "status" : "Draft", "tags" : [ "helpcenter", "knowledge base" ] }'

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "likeCount" : "0",
  "locale" : "en",
  "ownerId" : "4000000000059",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "isTrashed" : false,
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019059",
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "latestVersionStatus" : "Published",
  "myVote" : null,
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "usageCount" : "0",
  "commentCount" : "0",
  "rootCategoryId" : "4000000017276",
  "tags" : [ "first ticket" ],
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "translationId" : "4000000017294",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "latestPublishedVersion" : "1.0",
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "permalink" : "answering-your-first-ticket",
  "categoryId" : "4000000017287",
  "status" : "Published"
}

Validate permalink

This API validates if a permalink is available for a help article.

Attributes

Param Name

Data Type

Description

permalink

String

required

The permalink of Solution

locale

String

optional

Language

POST /api/v1/articles/checkPermalinkAvailability

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/checkPermalinkAvailability?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "permalink" : "how-to-open-account-2"
}'

Response Example

{
  "isAvailable" : false,
  "suggestion" : "how-to-open-account-2-18-12-2017"
}

Get article history

This API fetches the event history of an article.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

From index

limit

Integer

required,
default : 10,
range : 1-100

Number of records to fetch

events

String

optional

Actions happened on the article. We can give multiple events comma saperated. Allowed values CREATED, SEO_INFO_ADDED, TAGS_ADDED, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, TAGS_EDITED, STATUS_CHANGED, DISPALY_PERMISSION_CHANGED, PERMALINK_EDITED, OWNER_CHANGED, SECTION_CHANGED, TITLE_EDITED, SEO_INFO_EDITED, VERSION_CREATED, MOVED_TO_TRASH, RESTORED, ATTACHMENT_MODIFIED, VERSION_REVERTED, TAGS_DELETED, COMMENTS_ADDED, COMMENTS_EDITED, COMMENTS_DELETED, VERSION_UPDATED, VERSION_QUICKEDIT, VERSION_DELETED, SEO_TITLE_CHANGED, SEO_KEYWORDS_CHANGED, SEO_DESCRIPTION_CHANGED

userIds

Long

optional

User who did the action

fromTime

Timestamp

optional

From time. Time should be in GMT with format

toTime

Timestamp

optional

To time. Time should be in GMT with format

GET /api/v1/articles/{article_id}/history

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000000665001/history?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "deltedVersion" : [ "2.0", "3.0" ],
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "editedVersion" : "3.0",
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_QUICKEDIT",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "oldVersion" : "3.0",
    "locale" : "en",
    "event" : "VERSION_REVERTED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newVersion" : "4.0"
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "oldVersion" : "1.0",
    "locale" : "en",
    "event" : "VERSION_UPDATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newVersion" : "2.0"
  }, {
    "createdVersion" : "1.0",
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_CREATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "RESTORED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:26:28.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "MOVED_TO_TRASH",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newPermalink" : "test-article888",
    "eventTime" : "2018-03-15T14:19:28.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "PERMALINK_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "oldPermalink" : "test-article"
  }, {
    "eventTime" : "2018-03-15T14:16:06.000Z",
    "deletedTags" : [ "asda", "qwer", "ert" ],
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TAGS_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newTags" : [ "asda", "qwer", "ert" ],
    "oldTags" : [ "asda", "qwer" ],
    "eventTime" : "2018-03-15T14:15:52.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TAGS_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:15:40.000Z",
    "solutionId" : "1000000012768",
    "addedTags" : [ "qwer", "asda" ],
    "locale" : "en",
    "event" : "TAGS_ADDED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-13T07:44:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "deletedCommentId" : "1000000014007",
    "event" : "COMMENTS_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "editedCommentId" : "1000000014001",
    "eventTime" : "2018-03-13T07:43:45.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "COMMENTS_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "addedCommentId" : "1000000014001",
    "eventTime" : "2018-03-13T07:43:36.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "COMMENTS_ADDED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "removedAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_REMOVED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldAttachements" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_MODIFIED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ]
  }, {
    "addedAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_ADDED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newSectionId" : "1000000012741",
    "oldSectionId" : "1000000014013",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SECTION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldDisplayPermission" : "REGISTERED_USERS",
    "newDisplayPermission" : "AGENTS_ONLY",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "DISPALY_PERMISSION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newStatus" : "PUBLISH",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "STATUS_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newTitle" : "Test article dddddd",
    "eventTime" : "2018-03-13T07:32:35.000Z",
    "oldTitle" : "Test article",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TITLE_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_DESCRIPTION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_KEYWORDS_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldSEOTitle" : "ajsjkda",
    "newSEOTitle" : "ajsjkdaass",
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_TITLE_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-12T14:05:07.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "CREATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  } ]
}

Upload attachments

This API uploads files to your portal gallery.

Query Params

Param Name

Data Type

Description

workspaceId

String

required

Workspace id to which the attachement should be uploaded

attachmentType

String

required

Attachment type. Allowed values file, blob

File Params

file

Content-Type:multipart/form-data

attachment files for articles

POST /api/v1/articleAttachments

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articleAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&workspaceId=4fv34170cbb5ea8ed43a0932efaf53545818a&attachmentType=file
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "96b17694d63cd0f03eadbe4ae534f4ba993bb0",
  "extension" : "png",
  "name" : "Screen Shot 2018-12-28 at 7.21.58 PM.png",
  "filesize" : "62"
}

Move articles to trash

This API moves articles to the Recycle Bin

Attributes

Param Name

Data Type

Description

ids

list

required

Array of Entity id to be deleted

POST /api/v1/articles/moveToTrash

OAuth Scope

Desk.articles.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/moveToTrash?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "2345678987654323", "3456789087654567" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "2345678987654323",
    "errors" : null
  }, {
    "success" : "false",
    "id" : "3456789087654567",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Preview article

This API shows a preview of help articles, through which you can check the content for formatting, alignment, and grammar/spelling errors and get the look and feel of the help article even before publishing it.

Attributes

Param Name

Data Type

Description

title

String

required

The title of Solution

answer

String

required

The answer part of Solution

POST /api/v1/articles/preview

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/preview?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "answer" : "<div>Demo for article preview<br /></div><div>Lorem Ipsum is simply dummy text of the printing and typesetting industry. <br /></div>",
  "title" : "Demo for article preview"
}'

Response Example

{
  "answer" : "<div>Demo for article preview<br /></div><div>Lorem Ipsum is simply dummy text of the printing and typesetting industry. <br /></div>",
  "title" : "Demo for article preview"
}

Get article count

This API returns the number of articles published in the knowledge base of your help desk portal.

Query Params

Param Name

Data Type

Description

categoryId

Long

optional

Article count for given category. If categoryId is not given or null, it considered as all category i.e all department

authorId

Long

optional

Article count for the particular author

status

String

optional

Publishing status of the article to get count. Values allowed are Draft, Published, Review, Expired

permission

String

optional

Permissions to get the article count. Values allowed are ALL, REGISTEREDUSERS, AGENTS

GET /api/v1/articles/count

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/count?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&categoryId=30000087654324&authorId=2000087651124&status=Draft&permission=ALL
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "5"
}

Map articles to tickets

This API maps tickets with help articles to automatically suggest the same articles for similar tickets that arrive later.

Attributes

Param Name

Data Type

Description

ids

list

required

Array of Entity ids

POST /api/v1/tickets/{ticket_id}/notifyArticleUsage

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/10002398278/notifyArticleUsage?orgId=55560202
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "1000000022005", "1000000034567" ]
}'

Response Example

Get articles for manual sorting

This API lists the positions of help articles to enable manual sorting. Only leaf categories that have a maximum of 1000 articles can be repositioned.

GET /api/v1/kbCategory/{category_id}/repositionArticles

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbCategory/4000000013240/repositionArticles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000281023",
    "id" : "22372000000281023",
    "title" : "Importance of a Knowledge Base",
    "authorId" : "4000000012931"
  }, {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000209871",
    "id" : "22372000000209871",
    "title" : "Importance of a Knowledge Base",
    "authorId" : "4000000012931"
  } ]
}

Update article position

This API helps you manually sort articles in your knowledge base. Only leaf categories that have a maximum of 1000 articles can be repositioned.

Attributes

Param Name

Data Type

Description

ids

list

required

Array of Entity ids

POST /api/v1/kbCategory/{category_id}/repositionArticles

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbCategory/2000087651211/repositionArticles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "4000000083313", "4000000082105" ]
}'

Response Example

Get attachments

This API fetches the files attached to an article translation

Query Params

Param Name

Data Type

Description

from

Integer

optional,
range : >0

Index number starting from which the article attachments must be fetched.

limit

Integer

optional,
range : 1-30

Number of attachments to fetch

GET /api/v1/articles/{article_id}/translations/{locale}/attachments

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/9000067589998/translations/en-us/attachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "dkx4q10b53a2b6e844addaec2723cd4b07092",
  "extension" : "txt",
  "name" : "aadas1_2_3_5_54_.txt",
  "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "createdTime" : "2018-07-10T22:45:05.865Z",
  "filesize" : "62"
}

Upload and associate attachments

This API attaches files to translations and also uploads them to the knowledge base gallery

Query Params

Param Name

Data Type

Description

attachmentType

String

required

Attachment type. Allowed values file, blob

File Params

file

Content-Type:multipart/form-data

attachment files for articles

POST /api/v1/articles/{article_id}/translations/{locale}/attachments

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/9000067589998/translations/en-us/attachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&attachmentType=file
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "dkx4q10b53a2b6e844addaec2723cd4b07092",
  "extension" : "txt",
  "name" : "aadas1_2_3_5_54_.txt",
  "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "createdTime" : "2018-07-10T22:45:05.865Z",
  "filesize" : "62"
}

Attach files to translation

This API attaches specific files in the gallery to a translation

Attributes

Param Name

Data Type

Description

attachmentIds

String Array

required

Attachment associated with the Solution

POST /api/v1/articles/{article_id}/translations/{locale}/associateAttachments

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/9876543456789/translations/en-us/associateAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "1vq0db78bc1203a0645e0a38373b3bddf8d40" ]
}'

Response Example

{
  "data" : [ {
    "resourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40",
    "extension" : "txt",
    "name" : "aadas1_2_3_5_54_.txt",
    "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
    "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
    "createdTime" : "2018-07-10T22:45:05.865Z",
    "filesize" : "62"
  } ]
}

Dissociate attachments from translation

This API removes the file attachments from a translation

Attributes

Param Name

Data Type

Description

attachmentIds

String Array

required

Attachment associated with the Solution

POST /api/v1/articles/{article_id}/translations/{locale}/dissociateAttachments

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/dissociateAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "1vq0db78bc1203a0645e0a38373b3bddf8d40" ]
}'

Response Example

Like translation

This API adds a like (a positive reaction) to a translation

POST /api/v1/articles/{article_id}/translations/{locale}/like

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/like?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Dislike translation

This API adds a dislike (a negative reaction) to a translation.

POST /api/v1/articles/([0-9]+)/translations/{locale}/dislike

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/dislike?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get article statistics

This API fetches the basic insights related to an article

GET /api/v1/articles/{article_id}/insights

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/876546789087/insights?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "feedbackCount" : 0,
  "lastLikedTime" : "2018-11-20T14:03:07.000Z",
  "dislikeCount" : "0",
  "lastUsageTime" : null,
  "likeCount" : "1",
  "attachmentCount" : 0,
  "viewCount" : "0",
  "lastActivityTime" : "2018-11-20T14:03:07.000Z",
  "lastDislikedTime" : null,
  "usageCount" : "0",
  "commentCount" : 0
}

Get permalinks of translation

This API fetches the primary and secondary permalinks of a translation

GET /api/v1/articles/{article_id}/translations/{locale}/permalinks

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "primaryPermalink" : "how-to-open-account",
  "secondaryPermalinks" : [ "how-to-open-account-1", "how-to-open-account-3" ]
}

Update permalink of translation

This API updates the permalink of a translation and adds the old permalink to the redirection list

Attributes

Param Name

Data Type

Description

permalink

String

required

The permalink of Solution

isOldPermalinkNeeded

Boolean

optional

The variable that defines if permalink needs to be added to redirect list. By default, it is true

POST /api/v1/articles/{article_id}/translations/{locale}/permalinks/add

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "isOldPermalinkNeeded" : true, "permalink" : "how-to-open-account" }'

Response Example

{
  "primaryPermalink" : "how-to-open-account",
  "secondaryPermalinks" : [ "how-to-open-account-1", "how-to-open-account-3", "how-to-open-account-2" ]
}

Remove redirection permalink from translation

This API removes the redirection permalink from the redirection list of a translation

Attributes

Param Name

Data Type

Description

permalink

String

required

The permalink of Solution

POST /api/v1/articles/{article_id}/translations/{locale}/permalinks/removeSecondaryPermalink

OAuth Scope

Desk.articles.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks/removeSecondaryPermalink?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "permalink" : "how-to-open-account-2"
}'

Response Example

Download article translation attachment

This API downloads the attachment associated with article translation.

Query Params

Param Name

Data Type

Description

inline

boolean

optional

Display content inline

GET /api/v1/articles/{articleId}/translations/{locale}/attachments/{attachmentId}/content

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/6000000072015/translations/ja-jp/attachments/b96b17694d63cd0f03eadbe4/content?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Article Feedback

Article feedback refers to the text comments posted by users if they did not find a help article useful. This feedback can be used to improve the help article(s).

Example

{ "ticket" : { "ticketNumber" : "163", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913", "id" : "22372000001389007", "deletedTime" : "2018-10-07T10:27:20.000Z", "deletedBy" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo", "name" : "Zylker", "id" : "22372000000761001", "status" : "ACTIVE", "zuid" : "15223452" } }, "contactId" : "22372000001386025", "contact" : { "photoURL" : null, "name" : "John", "id" : "22372000001386025" }, "createdTime" : "2018-10-07T15:55:24.000Z", "id" : "22372000001386045", "resolution" : { "modifiedTime" : "2020-12-03T05:08:21.000Z", "createdBy" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553", "name" : "Charlie", "id" : "22372000000000063", "status" : "ACTIVE", "zuid" : "15224552" }, "feedbackId" : "227800000075038", "createdTime" : "2020-12-03T05:08:21.000Z", "modifiedBy" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553", "name" : "Charlie", "id" : "22372000000000063", "status" : "ACTIVE", "zuid" : "15224552" }, "id" : "22372340000106009", "resolution" : "Content has been modified in user basis", "contentType" : "PLAIN_TEXT" }, "ticketId" : "22372000001389007", "content" : "Please add pricing details in tabular columns", "article" : { "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553", "name" : "Charlie", "id" : "22372000000000063", "status" : "ACTIVE", "zuid" : "15224552" }, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011", "id" : "22372000001370011", "locale" : "en", "title" : "Pricing details" }, "status" : "RESOLVED" }

List feedback comments on article translation

This API lists a particular number of comments received on a translation of an article, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Int

optional,
range : >0

Index number, starting from which the comments must be fetched. Default value is 1.

limit

Int

optional,
range : 1-50

Number of comments to list. Default value is 10.

sortBy

String

optional

Key that sorts the comments based on a specific attribute: createdTime. To sort the comments in descending order, append a '-' before the value

createdTimeRange

timestamp

optional

Key that filters comments created within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

include

string

optional,
max chars : 100

Additional information related to the comments. Values allowed are: ticket, contact and resolution.

GET /api/v1/articles/{article_id}/translations/{locale}/feedbacks

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000001370011/translations/en-us/feedbacks?from=1&limit=10&sortBy=-createdTime&include=ticket,contact,resolution
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "163",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
      "id" : "22372000001389007",
      "deletedTime" : "2018-10-07T10:27:20.000Z",
      "deletedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
        "name" : "Zylker",
        "id" : "22372000000761001",
        "status" : "ACTIVE",
        "zuid" : "15223452"
      }
    },
    "contactId" : "22372000001386025",
    "contact" : {
      "photoURL" : null,
      "name" : "John",
      "id" : "22372000001386025"
    },
    "createdTime" : "2018-10-07T15:55:24.000Z",
    "id" : "22372000001386045",
    "resolution" : {
      "modifiedTime" : "2020-12-03T05:08:21.000Z",
      "createdBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "feedbackId" : "227800000075038",
      "createdTime" : "2020-12-03T05:08:21.000Z",
      "modifiedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "id" : "22372340000106009",
      "resolution" : "Content has been modified in user basis",
      "contentType" : "PLAIN_TEXT"
    },
    "ticketId" : "22372000001389007",
    "content" : "Please add pricing details in tabular columns",
    "article" : {
      "author" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
      "id" : "22372000001370011",
      "locale" : "en",
      "title" : "Pricing details"
    },
    "status" : "RESOLVED"
  } ]
}

Get details of feedback comment

This API fetches the details of a particular feedback comment.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the comment. Values allowed are: ticket, contact and resolution.

GET /api/v1/articleFeedbacks/{feedback_id}

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045?&include=ticket,contact,resolution
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "ticket" : {
    "ticketNumber" : "163",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
    "id" : "22372000001389007",
    "deletedTime" : "2018-10-07T10:27:20.000Z",
    "deletedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
      "name" : "Zylker",
      "id" : "22372000000761001",
      "status" : "ACTIVE",
      "zuid" : "15223452"
    }
  },
  "contactId" : "22372000001386025",
  "contact" : {
    "photoURL" : null,
    "name" : "John",
    "id" : "22372000001386025"
  },
  "createdTime" : "2018-10-07T15:55:24.000Z",
  "id" : "22372000001386045",
  "resolution" : {
    "modifiedTime" : "2020-12-03T05:08:21.000Z",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "feedbackId" : "227800000075038",
    "createdTime" : "2020-12-03T05:08:21.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "id" : "22372340000106009",
    "resolution" : "Content has been modified in user basis",
    "contentType" : "PLAIN_TEXT"
  },
  "ticketId" : "22372000001389007",
  "content" : "Please add pricing details in tabular columns",
  "article" : {
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
    "id" : "22372000001370011",
    "locale" : "en",
    "title" : "Pricing details"
  },
  "status" : "RESOLVED"
}

List feedback comments

This API lists a particular number of comments received on an article, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Int

optional,
range : >0

Index number, starting from which the comments must be fetched. Default value is 1.

limit

Int

optional,
range : 1-50

Number of comments to list. Default value is 10.

sortBy

String

optional

Key that sorts the comments based on a specific attribute: createdTime. To sort the comments in descending order, append a '-' before the value.

include

string

optional,
max chars : 100

Additional information related to the comments. Values allowed are: ticket, contact and resolution.

departmentIds

String

optional

Filter article feedback comments based on department ids

rootCategoryIds

String

optional

Filter article feedback comments based on rootCategoryIds

timeRange

String

optional

Key that filters comments created within a specific date and time range. Enter the time limit in the formats of
LAST_7_DAYS,

LAST_30_DAYS,

LAST_365_DAYS,

yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ
. Default value : LAST_7_DAYS.

locale

String

optional

Locale of an article translation in which feedback comments to be fetched

GET /api/v1/articleFeedbacks

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articleFeedbacks?from=1&limit=10&sortBy=-createdTime&rootCategoryIds=2237200000137333&include=ticket,contact,resolution&timeRange=LAST_365_DAYS&locale=en
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "163",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
      "id" : "22372000001389007",
      "deletedTime" : "2018-10-07T10:27:20.000Z",
      "deletedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
        "name" : "Zylker",
        "id" : "22372000000761001",
        "status" : "ACTIVE",
        "zuid" : "15223452"
      }
    },
    "contactId" : "22372000001386025",
    "contact" : {
      "photoURL" : null,
      "name" : "John",
      "id" : "22372000001386025"
    },
    "createdTime" : "2018-10-07T15:55:24.000Z",
    "id" : "22372000001386045",
    "resolution" : {
      "modifiedTime" : "2020-12-03T05:08:21.000Z",
      "createdBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "feedbackId" : "227800000075038",
      "createdTime" : "2020-12-03T05:08:21.000Z",
      "modifiedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "id" : "22372340000106009",
      "resolution" : "Content has been modified in user basis",
      "contentType" : "PLAIN_TEXT"
    },
    "ticketId" : "22372000001389007",
    "content" : "Please add pricing details in tabular columns",
    "article" : {
      "author" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
      "id" : "22372000001370011",
      "locale" : "en",
      "title" : "Pricing details"
    },
    "status" : "RESOLVED"
  } ]
}

Delete feedback comment

This API deletes a particular feedback comment from an article.

DELETE /api/v1/articleFeedbacks/{feedback_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Convert feedback comment into ticket

This API adds a feedback comment as a ticket in your help desk portal and assigns it to the author of the article.

Attributes

Param Name

Data Type

Description

POST /api/v1/articleFeedbacks/{feedback_id}/addAsTicket

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045/addAsTicket
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "ticket" : {
    "ticketNumber" : "163",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
    "id" : "22372000001389007",
    "deletedTime" : "2018-10-07T10:27:20.000Z",
    "deletedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
      "name" : "Zylker",
      "id" : "22372000000761001",
      "status" : "ACTIVE",
      "zuid" : "15223452"
    }
  },
  "contactId" : "22372000001386025",
  "createdTime" : "2018-10-07T15:55:24.000Z",
  "id" : "22372000001386045",
  "ticketId" : "22372000001389007",
  "content" : "Please add pricing details in tabular columns",
  "article" : {
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
    "id" : "22372000001370011",
    "locale" : "en",
    "title" : "Pricing details"
  },
  "status" : "RESOLVED"
}

KBCategory

Categories are groups using which you can organize help articles in your knowledge base. You can create categories, based on the products/services you offer or the nature of the issues your customers report.

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the category

parentCategoryId

long

ID of the parent category

helpcenterId

long

ID of the help center to which the knowledge base belongs

articleViewType

String

View to apply while listing help articles. Values allowed are: LISTVIEW and OVERVIEW.

isVisibleInHC

boolean

Key that specifies whether the category must be visible in the help center or not

isReview

boolean

Key that specifies whether review must be enabled for the category or not

reviewOwners

list

IDs of users who must review the category

associatedDepartments

list

List of departments to associate with the category

description

string

A brief description of the category

logo

long

Logo for the category

featuredCategory

boolean

Key that specifies whether the category must be featured in the help center or not

visibility

String

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, and NONE.

level

int

Navigation depth of the category

~~departmentId~~

deprecated

long

ID of the department to associate with the category

childOrder

list

Order of sub-categories within the category

long

Unique ID of the category

articlesCount

int

Number of help articles under the category

workspaceId

long

ID of the Zoho Workdrive folder (Gallery) associated with the category

order

int

Position of the category in the overall order of categories of the same level

child

list

List of sub-categories

groupIds

list

List of group IDs

articlePermission

String

Visibility setting of articles, based on the visibility setting of the category

Example

{ "modifiedTime" : "2020-06-24T11:46:42.000Z", "articleViewType" : "LISTVIEW", "visibility" : "NONE", "groups" : [ ], "logoUrl" : null, "associatedDepartmentIds" : [ "4000000013244" ], "encryptedWorkspaceId" : "2d6dd8bff74bb212fa6a72a9d8ab5102f704587dd12c18d23a1747934db6b9266a742c45a7dc4c04c7b8abebb10f37508611a7fb7471f1de79d8fa5b104f3350", "helpcenterId" : "4000000016818", "isReviewEnabled" : false, "isTrashed" : false, "createdBy" : { "photoURL" : null, "name" : "Hill", "id" : "4000000000059", "status" : "ACTIVE", "zuid" : "343224" }, "translations" : [ { "modifiedTime" : "2020-06-24T11:46:42.000Z", "createdBy" : { "photoURL" : null, "name" : "Hill", "id" : "4000000000059", "status" : "ACTIVE", "zuid" : "343224" }, "name" : "Hill", "description" : null, "createdTime" : "2020-06-24T11:46:42.000Z", "modifiedBy" : { "photoURL" : null, "name" : "Hill", "id" : "4000000000059", "status" : "ACTIVE", "zuid" : "343224" }, "id" : "4000000019051", "permalink" : "Hill", "locale" : "en", "categoryId" : "4000000017276" } ], "name" : "Hill", "createdTime" : "2020-06-24T11:46:42.000Z", "modifiedBy" : { "photoURL" : null, "name" : "Hill", "id" : "4000000000059", "status" : "ACTIVE", "zuid" : "343224" }, "id" : "4000000017276", "status" : "SHOW_IN_HELPCENTER", "order" : "1", "workspaceId" : "a7iyye68bf585aebb477a936526f1ce7980b0" }

Create root category

This API creates a root category in your knowledge base.

Attributes

Param Name

Data Type

Description

name

String

required

Name of the category

description

String

required

A brief description of the category

status

String

required,
default : HIDE_IN_HELPCENTER

Activation status of the category

visibility

String

required,
default : NONE

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, NONE, and PRIVATE_IP.

groupIds

list

optional

List of group IDs

articleViewType

String

required

View to apply while listing help articles. Values allowed are: LISTVIEW and OVERVIEW.

isReviewEnabled

boolean

required

Key that specifies whether the category must be reviewed or not

logoId

long

required

ID of the logo to set for the category

associatedDepartmentIds

list

required

IDs of the departments associated with the category

helpcenterId

long

optional

ID of the help center to which the category belongs

POST /api/v1/kbRootCategories

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "isReviewEnabled" : false, "articleViewType" : "LISTVIEW", "visibility" : "ALL_USERS", "translations" : [ { "name" : "Zoho Desk", "description" : "A helpdesk software", "permalink" : "zoho-desk", "locale" : "en" } ], "name" : "Zoho Desk", "logoId" : "25", "feedbackTicketConversionPreference" : { "departmentId" : "5000000063895", "assigneeId" : "5000000000059", "status" : "ENABLED" }, "status" : "SHOW_IN_HELPCENTER", "associatedDepartmentIds" : [ "5000000063895" ] }'

Response Example

{
  "modifiedTime" : "2020-01-02T15:26:51.000Z",
  "visibility" : "ALL_USERS",
  "articleViewType" : "LISTVIEW",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "feedbackTicketConversionPreference" : {
    "departmentId" : "5000000063895",
    "assignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
      "name" : "Charlie Marlie",
      "id" : "5000000000059",
      "status" : "ACTIVE",
      "zuid" : "15224545"
    },
    "status" : "ENABLED"
  },
  "associatedDepartmentIds" : [ "5000000063895" ],
  "encryptedWorkspaceId" : "uhahs234dha2342342424da2342342342",
  "helpcenterId" : "5000000015871",
  "isReviewEnabled" : true,
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-02T15:24:42.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Zoho Desk",
    "description" : "A helpdesk software",
    "createdTime" : "2020-01-02T15:24:42.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000336004",
    "permalink" : "zoho-desk",
    "locale" : "en",
    "categoryId" : "5000000319037"
  } ],
  "name" : "Zoho Desk",
  "createdTime" : "2019-12-30T12:10:30.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000319037",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "3",
  "workspaceId" : "asa432da353sda"
}

Upload logo image

This API is used to upload an image to be used as logo

File Params

file

Content-Type:multipart/form-data

POST /api/v1/kbCategoryLogo

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbCategoryLogo
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "id" : "2029254000000178001"
}

Create a section

This API creates a section in your helpdesk

Attributes

Param Name

Data Type

Description

name

String

required

Section Name

parentCategoryId

Long

required

Parent id (either section or rootCategoryId) below which we need to create a section

description

String

optional

A short description of the section

logoId

long

optional

Logo for each category

status

String

optional,
default : HIDE_IN_HELPCENTER

Status of the section

visibility

String

optional,
default : NONE

Visibility of the section. Values allowed are
AGENTS
,
GROUP_USERS
,
ALL_USERS
,
NONE
,
PRIVATE_IP

groupIds

list

optional

group ids list

articlePermission

String

optional

To update the article permission based on category visibility

POST /api/v1/kbSections

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbSections
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "articlePermission" : "ALL", "translations" : [ { "name" : "For Agents", "description" : "Section 1 description", "locale" : "en-us", "permalink" : "for-agents" } ], "name" : "For Agents", "description" : "Section 1 description", "parentCategoryId" : 5000000340014, "logoId" : "10", "status" : "SHOW_IN_HELPCENTER" }'

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Update a section

This API updates a section in your helpdesk

Attributes

Param Name

Data Type

Description

name

String

optional

Section Name

description

String

optional

A short description of the section

logoId

long

optional

Logo for each category

status

String

optional,
default : HIDE_IN_HELPCENTER

Status of the section

visibility

String

optional,
default : NONE

Visibility of the section. Values allowed are
AGENTS
,
GROUP_USERS
,
ALL_USERS
,
PRIVATE_IP
,
NONE

groupIds

list

optional

group ids list

articlePermission

String

optional

To update the article permission based on category visibility

PATCH /api/v1/kbSections/{sectionId}

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/kbSections/5000000340014
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "articlePermission" : "REGISTEREDUSERS",
  "translations" : [ {
    "name" : "section name updated",
    "locale" : "pl-pl"
  } ],
  "status" : "HIDE_IN_HELPCENTER"
}'

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Get a section

This API fetches a section in your helpdesk

Query Params

Param Name

Data Type

Description

include

String

optional

Include params are publicArticlesCount, allArticlesCount

GET /api/v1/kbSections/{sectionId}

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbSections/5000000340014
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Get root category

This API fetches the details of a root category.

Query Params

Param Name

Data Type

Description

include

String

optional

Additional information related to the category. Values allowed are: publicArticlesCount and allArticlesCount.

GET /api/v1/kbRootCategories/{rootCategoryId}

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000340014
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-01-02T15:26:51.000Z",
  "visibility" : "ALL_USERS",
  "articleViewType" : "LISTVIEW",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "feedbackTicketConversionPreference" : {
    "departmentId" : "5000000063895",
    "assignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
      "name" : "Charlie Marlie",
      "id" : "5000000000059",
      "status" : "ACTIVE",
      "zuid" : "15224545"
    },
    "status" : "ENABLED"
  },
  "associatedDepartmentIds" : [ "5000000063895" ],
  "encryptedWorkspaceId" : "uhahsdhada",
  "helpcenterId" : "5000000015871",
  "isReviewEnabled" : true,
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-02T15:24:42.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Root category name",
    "description" : "description of root",
    "createdTime" : "2020-01-02T15:24:42.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000336004",
    "permalink" : "root-category-name",
    "locale" : "en",
    "categoryId" : "5000000319037"
  } ],
  "name" : "Root category name",
  "createdTime" : "2019-12-30T12:10:30.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000319037",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "3",
  "workspaceId" : "asadasda"
}

Get a category tree

This API fetches the full tree of a root category in your helpdesk

Query Params

Param Name

Data Type

Description

locale

String

optional

Locale of the translated name

sortBy

String

optional

Sort order of the categories. Allowed values : name, order

includeTrash

Boolean

optional

Presence flag of the category

include

String

optional

Include params are publicArticlesCount, allArticlesCount

GET /api/v1/kbRootCategories/{rootCategoryId}/categoryTree

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000340014/categoryTree&sortBy=order&includeTrash=true&locale=en&include=publicArticlesCount,allArticlesCount
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "visibility" : "ALL_USERS",
  "allArticlesCount" : "0",
  "description" : "test",
  "locale" : "en",
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "publicArticlesCount" : "0",
  "isTrashed" : false,
  "children" : [ {
    "visibility" : "ALL_USERS",
    "allArticlesCount" : "0",
    "description" : "Desk",
    "locale" : "en",
    "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
    "rootCategoryId" : "5000000066427",
    "publicArticlesCount" : "0",
    "isTrashed" : false,
    "children" : [ {
      "visibility" : "ALL_USERS",
      "allArticlesCount" : "0",
      "description" : "Section 2",
      "locale" : "en",
      "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
      "rootCategoryId" : "5000000066427",
      "publicArticlesCount" : "0",
      "isTrashed" : false,
      "children" : [ ],
      "translations" : [ {
        "name" : "section 2 en",
        "description" : null,
        "id" : "5000000341003",
        "permalink" : "section-2-en",
        "locale" : "en"
      } ],
      "name" : "Section 2",
      "parentCategoryId" : "5000000340014",
      "id" : "5000000341001",
      "status" : "SHOW_IN_HELPCENTER",
      "order" : "1"
    } ],
    "translations" : [ {
      "name" : "For Agents",
      "description" : null,
      "id" : "5000000340016",
      "permalink" : "for-agents",
      "locale" : "en"
    } ],
    "name" : "Desk",
    "parentCategoryId" : "5000000066427",
    "id" : "5000000340014",
    "status" : "SHOW_IN_HELPCENTER",
    "order" : "5"
  } ],
  "translations" : [ {
    "name" : "Desk",
    "description" : "Helpdesk-software",
    "id" : "5000000265103",
    "permalink" : "desk",
    "locale" : "en"
  } ],
  "name" : "test",
  "id" : "5000000066427",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "1"
}

List root categories

This API lists a particular number of root categories, based on the limit defined.

Query Params

Param Name

Data Type

Description

locale

String

optional

Language of the category

sortBy

String

optional

Key that sorts the categories, based on a specific attribute: name or order

from

Int

required,
default : 1,
range : >0

Index number, starting from which the categories must be fetched

limit

Int

required,
default : 50,
range : 1-500

Number of categories to list

searchValue

String

optional

Keyword for searching for a particular category

status

String

optional

Activation status of the category. Values allowed are: SHOW_IN_HELPCENTER, HIDE_IN_HELPCENTER, and DISABLED.

isTrashed

boolean

optional

Key that denotes whether the category is deleted or not

isReviewEnabled

boolean

optional

Key that specifies whether the category must be reviewed or not

visibility

String

optional

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, and NONE.

departmentId

String

optional

ID of the department associated with the category

helpcenterId

String

optional

ID of the help center to which the category belongs

include

String

optional

Additional information related to the category. Values allowed are: publicArticlesCount, allArticlesCount, and sectionsCount.

GET /api/v1/kbRootCategories

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-01-05T13:18:07.000Z",
    "visibility" : "ALL_USERS",
    "articleViewType" : "LISTVIEW",
    "allArticlesCount" : "11",
    "groups" : [ ],
    "sectionsCount" : "7",
    "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
    "feedbackTicketConversionPreference" : {
      "departmentId" : "5000000063895",
      "assignee" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
        "name" : "Charlie Marlie",
        "id" : "5000000000059",
        "status" : "ACTIVE",
        "zuid" : "15224545"
      },
      "status" : "ENABLED"
    },
    "associatedDepartmentIds" : [ "5000000063895" ],
    "publicArticlesCount" : "3",
    "encryptedWorkspaceId" : "04bd200bc14c4cac0c0026a0342c1f21263012407fa56109a37788e786a96ec0383c1eeb08849f9be78a6f7b8b8f31033dde60d41ad95443c6570636db1a9b20",
    "helpcenterId" : "5000000015871",
    "isReviewEnabled" : false,
    "isTrashed" : false,
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "translations" : [ {
      "modifiedTime" : "2019-10-10T06:18:39.000Z",
      "createdBy" : {
        "photoURL" : null,
        "name" : "Zylker",
        "id" : "5000000015867",
        "status" : "ACTIVE",
        "zuid" : "343224"
      },
      "name" : "Zoho Desk",
      "description" : "A helpdesk software",
      "createdTime" : "2019-06-24T07:03:39.000Z",
      "modifiedBy" : {
        "photoURL" : null,
        "name" : "Zylker",
        "id" : "5000000015867",
        "status" : "ACTIVE",
        "zuid" : "343224"
      },
      "id" : "5000000265103",
      "permalink" : "zoho-desk",
      "locale" : "en",
      "categoryId" : "5000000066427"
    } ],
    "name" : "Zoho Desk",
    "createdTime" : "2019-06-24T07:03:39.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000066427",
    "status" : "SHOW_IN_HELPCENTER",
    "order" : "1",
    "workspaceId" : "ponaz00368c36c9274809bf96849b392f8d67"
  } ]
}

Get review owners

This API fetches review owners of a root category in your helpdesk

Query Params

Param Name

Data Type

Description

sortBy

String

optional

Sort order of the owners. Allowed values : firstName, lastName

from

Int

required,
default : 1,
range : >0

Offset value

limit

Int

required,
default : 50,
range : 1-100

Number of objects

searchValue

String

optional

Search string

GET /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867"
  } ]
}

Add review owner

This API adds review owners of a root category in your helpdesk

Attributes

Param Name

Data Type

Description

reviewOwnerIds

list

required

review owner ids list

POST /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners/add

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners/add
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reviewOwnerIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Remove review owner

This API removes review owners of a root category in your helpdesk

Attributes

Param Name

Data Type

Description

reviewOwnerIds

list

required

review owner ids list

POST /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners/remove

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners/remove
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reviewOwnerIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Add a permalink to a root catgeory

This API adds a permalink to a root category translation

Attributes

Param Name

Data Type

Description

permalink

String

required

The permalink of Solution

isOldPermalinkNeeded

Boolean

optional

The variable that defines if permalink needs to be added to redirect list. By default, it is true

POST /api/v1/kbRootCategories/{rootCategoryId}/translations/{locale}/permalinks/add

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/translations/en/add
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isOldPermalinkNeeded" : true,
  "permalink" : "new-permalink"
}'

Response Example

{
  "data" : [ {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : true,
    "createdTime" : "2020-05-01T14:16:43.000Z",
    "permalink" : "autobot"
  }, {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : false,
    "createdTime" : "2020-05-01T14:12:29.000Z",
    "permalink" : "transformers"
  }, {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : false,
    "createdTime" : "2020-05-01T14:12:24.000Z",
    "permalink" : "flash"
  } ]
}

Remove a permalink of a root category

This API removes a permalink of a root category translation

Attributes

Param Name

Data Type

Description

permalink

String

required

The permalink of Solution

POST /api/v1/kbRootCategories/{rootCategoryId}/translations/{locale}/permalinks/remove

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/translations/en/remove
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "permalink" : "permalink-2"
}'

Response Example

{
  "primaryPermalink" : "new-permalink",
  "secondaryPermalinks" : [ "permalink-3" ]
}

Contracts

Contracts help you organize your desk commitments, enabling you to deliver more professional and dedicated customer service. By defining contracts, you can determine the level of service to offer and set the contract period for an account or a product.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the contract

associatedSLAId

long

ID of the SLA associated with the contract

accountId

long

ID of the account associated with the contract

departmentId

long

ID of the department to which the contract belongs

productId

long

ID of the product associated with the contract

contractNumber

string

Serial number of the contract

notificationAgentIds

list

List of agents to be notified

notifyBefore

int

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

notifyOn

date

The date when the contract expiry notification must be sent

startDate

date

Date from which the contract is valid

endDate

date

Date until which the contract is valid

ownerId

long

ID of the contract owner

createdBy

string

User who created the contract

modifiedBy

string

User who modified the contract

createdTime

timestamp

Time of creating the contract

modifiedTime

timestamp

Time of modifying the contract

contractName

string

Name of the contract

description

string

A short description of the contract

~~customFields~~

deprecated

list

User-defined fields associated with the contract

list

User-defined fields associated with the contract

Example

{ "associatedSLAId" : "5000000007671", "modifiedTime" : "2018-01-15T11:13:04.000Z", "cf" : { "cf_mycustomfield1" : "hello" }, "productId" : "5000000009328", "endDate" : "2019-01-10", "departmentId" : "5000000007235", "notifyBefore" : "5", "contractNumber" : "101", "description" : null, "ownerId" : "5000000009148", "notificationAgentIds" : [ "5000000009148" ], "accountId" : "5000000009326", "createdBy" : "5000000009148", "notifyOn" : "2019-01-05", "createdTime" : "2018-01-10T11:29:41.000Z", "contractName" : "Ticket Resolution Contract for 5 Star Crisps", "modifiedBy" : "5000000009148", "id" : "5000000009331", "startDate" : "2018-01-10" }

Get a contract

This API fetches a single contract from your helpdesk.

GET api/v1/contracts/{{contract_id}}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contracts/5000000009331
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "associatedSLAId" : "5000000007671",
  "modifiedTime" : "2018-01-15T11:13:04.000Z",
  "cf" : {
    "cf_mycustomfield1" : "hello"
  },
  "productId" : "5000000009328",
  "endDate" : "2019-01-10",
  "departmentId" : "5000000007235",
  "notifyBefore" : "5",
  "contractNumber" : "101",
  "description" : null,
  "ownerId" : "5000000009148",
  "notificationAgentIds" : [ "5000000009148" ],
  "accountId" : "5000000009326",
  "createdBy" : "5000000009148",
  "notifyOn" : "2019-01-05",
  "createdTime" : "2018-01-10T11:29:41.000Z",
  "contractName" : "Ticket Resolution Contract for 5 Star Crisps",
  "modifiedBy" : "5000000009148",
  "id" : "5000000009331",
  "startDate" : "2018-01-10"
}

List all contracts

To get a list of contracts

Query Params

Param Name

Data Type

Description

from

integer

optional

From index

limit

integer

optional,
range : 1-100

Number of contracts to fetch

viewId

integer

optional

ID of the view to apply while fetching the resources

departmentId
see documentation

long

optional

ID of the department from which the contracts must be fetched

accountId
see documentation

long

optional

ID of the account associated with the contract

ownerId

long

optional

ID of contract owner

sortBy

string

optional,
max chars : 100

Parameter that sorts contracts by one of these attributes:
accountName,

contractName,

contractEndDate,

contractStartDate,

createdTime, or

modifiedTime.
The default order of sorting is ascending. To sort in descending order, prefix a - with the parameter.

include
see documentation

string

optional,
max chars : 100

Allowed Value is: accounts

GET api/v1/contracts

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contracts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "FUTURE",
    "productId" : null,
    "endDate" : "2018-11-10",
    "departmentId" : "10000000010762",
    "contractName" : "C2",
    "id" : "10000000270023",
    "ownerId" : "10000000012902",
    "startDate" : "2018-10-10"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-10",
    "departmentId" : "10000000010762",
    "contractName" : "New",
    "id" : "10000000270045",
    "ownerId" : "10000000012902",
    "startDate" : "2018-09-09"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272001",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2018-12-11",
    "departmentId" : "10000000010762",
    "contractName" : "THIRD",
    "id" : "10000000272013",
    "ownerId" : "10000000012902",
    "startDate" : "2018-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272037",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2019-03-11",
    "departmentId" : "10000000010762",
    "contractName" : "Fourth ACC",
    "id" : "10000000272049",
    "ownerId" : "10000000012902",
    "startDate" : "2018-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272071",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-12",
    "departmentId" : "10000000010762",
    "contractName" : "old",
    "id" : "10000000272083",
    "ownerId" : "10000000012902",
    "startDate" : "2017-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2018-09-30",
    "departmentId" : "10000000010762",
    "contractName" : "FUTURE 1",
    "id" : "10000000273003",
    "ownerId" : "10000000012902",
    "startDate" : "2018-09-15"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "FUTURE",
    "productId" : null,
    "endDate" : "2018-12-11",
    "departmentId" : "10000000010762",
    "contractName" : "FUTURE 3",
    "id" : "10000000273025",
    "ownerId" : "10000000012902",
    "startDate" : "2018-11-11"
  } ]
}

Create a contract

This API creates a contract in your helpdesk.

Attributes

Param Name

Data Type

Description

associatedSLAId

long

required

ID of the SLA associated with the contract

accountId

long

required

ID of the account associated with the contract

departmentId

long

required

ID of the department to which the contract belongs

productId

long

optional

ID of the product associated with the contract

contractNumber

string

optional,
max chars : 50

Serial number of the contract

notificationAgentIds

list

optional

List of agents to be notified

notifyBefore

int

optional

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

startDate

date

required

Date from which the contract is valid

endDate

date

optional

Date until which the contract is valid

ownerId

long

required

ID of the contract owner

contractName

string

required,
max chars : 80

Name of the contract

description

string

optional,
max chars : 65535

A short description of the contract

~~customFields~~

deprecated

list

optional

User-defined fields associated with the contract

list

optional

User-defined fields associated with the contract

POST /api/v1/contracts

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contracts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "associatedSLAId" : "10000000062047", "cf" : { "cf_mycustomfield1" : "Some Value" }, "productId" : null, "endDate" : "2019-07-23", "departmentId" : "10000000013228", "notifyBefore" : "3", "description" : "My Description", "contractNumber" : 9495, "ownerId" : "10000000012816", "notificationAgentIds" : [ "10000000012816" ], "accountId" : "10000000012985", "contractName" : "MyContractName", "startDate" : "2018-07-23" }'

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-07-24T07:31:57.075Z",
  "cf" : {
    "cf_mycustomfield1" : "Some Value"
  },
  "productId" : null,
  "endDate" : "2019-07-23",
  "departmentId" : "10000000013228",
  "notifyBefore" : "3",
  "contractNumber" : "9495",
  "description" : "My Description",
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "createdBy" : "10000000012816",
  "notifyOn" : "2019-07-20",
  "createdTime" : "2018-07-24T07:31:57.075Z",
  "contractName" : "MyContractName",
  "modifiedBy" : "10000000012816",
  "id" : "10000000082016",
  "startDate" : "2018-07-23"
}

Update a contract

This API updates the details of an existing contract.

Attributes

Param Name

Data Type

Description

associatedSLAId

long

optional

ID of the SLA associated with the contract

accountId

long

optional

ID of the account associated with the contract

departmentId

long

optional

ID of the department to which the contract belongs

productId

long

optional

ID of the product associated with the contract

contractNumber

string

optional,
max chars : 50

Serial number of the contract

notificationAgentIds

list

optional

List of agents to be notified

notifyBefore

int

optional

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

startDate

date

optional

Date from which the contract is valid

endDate

date

optional

Date until which the contract is valid

ownerId

long

optional

ID of the contract owner

contractName

string

optional,
max chars : 80

Name of the contract

description

string

optional,
max chars : 65535

A short description of the contract

~~customFields~~

deprecated

list

optional

User-defined fields associated with the contract

list

optional

User-defined fields associated with the contract

PATCH /api/v1/contracts/{contract_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/contracts/10000000078091
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "associatedSLAId" : "10000000062047", "cf" : { "cf_mycustomfield1" : "Some Update Value" }, "productId" : null, "endDate" : "2019-09-15", "departmentId" : "10000000013228", "notifyBefore" : "5", "description" : "My Description Updated", "contractNumber" : 9496, "ownerId" : "10000000012816", "notificationAgentIds" : [ "10000000012816" ], "accountId" : "10000000012985", "contractName" : "My Updated Contract Name", "startDate" : "2018-08-14" }'

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-07-24T07:33:11.728Z",
  "cf" : {
    "cf_mycustomfield1" : "Some Update Value"
  },
  "productId" : null,
  "endDate" : "2019-09-15",
  "departmentId" : "10000000013228",
  "notifyBefore" : "5",
  "contractNumber" : "9496",
  "description" : "My Description Updated",
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "createdBy" : "10000000012816",
  "notifyOn" : "2019-09-10",
  "createdTime" : "2018-07-24T07:31:57.000Z",
  "contractName" : "My Updated Contract Name",
  "modifiedBy" : "10000000012816",
  "id" : "10000000082016",
  "startDate" : "2018-08-14"
}

Delete contracts

This API moves contracts to the Recycle Bin of your help desk portal

Attributes

Param Name

Data Type

Description

contractIds

list

required

IDs of the contracts that you want to delete

POST api/v1/contracts/moveToTrash

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contracts/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contractIds" : [ "10000000014816", "1000000001243", "10000000018818" ]
}'

Response Example

Timetracking

Time tracking refers to the process of recording the time agents take to resolve tickets. This information can be recorded manually or automatically, based on your organization's requirement and preference. APIs related to this endpoint help you configure the settings for automated time tracking.

ATTRIBUTES

Attribute Name

Data Type

Description

isTimeTracking

boolean

depId

long

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

Key that returns if the time tracked is billable or not.

billingType

String

Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

fixedCost

Double

Cost fixed for either billing category - by ticket or by agent.

agents

show Attributes

list

List of agents in the department

profiles

show Attributes

list

List of user profiles defined in the department

timerAction

String

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

show Attributes

list

Activity preference(s)

ticketPreference

show Attributes

list

Ticket preference(s)

Example

{ "ticketPreference" : { "autoTrackAction" : { "fieldUpdate" : true, "onChatComplete" : true, "onRemoteAssist" : true, "commentActions" : true, "approvalActions" : true, "sendReply" : true, "manualDraft" : true, "resolutionActions" : true, "attachmentActions" : true }, "isReviewTime" : "false", "isAutoPause" : "true", "isAutoTimer" : "true", "isHideTimeTracking" : "false" }, "billingType" : "SPECIFIC_COST_PER_AGENT", "activityPreference" : { "isTasksEnabled" : "true", "trackMode" : "CONSECUTIVE", "isEventsEnabled" : "true", "canAutoTrackCalls" : "true" }, "fixedCost" : "1000", "profiles" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ], "depId" : "1892000000006907", "isTimeTracking" : "true", "timerAction" : "ADD", "isBillable" : true, "agents" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ] }

Create TimeTrackSettings

This API adds a TimeTracking configuration to your helpdesk.

Attributes

Param Name

Data Type

Description

isTimeTracking

boolean

required

depId

long

required

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

optional

Key that returns if the time tracked is billable or not.

billingType

String

optional

Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

fixedCost

Double

optional

Cost fixed for either billing category - by ticket or by agent.

agents

list

optional

List of agents in the department

profiles

list

optional

List of user profiles defined in the department

timerAction

String

optional

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

list

optional

Activity preference(s)

ticketPreference

list

optional

Ticket preference(s)

POST /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/timeTrackSettings
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "ticketPreference" : { "autoTrackAction" : { "fieldUpdate" : true, "onChatComplete" : true, "onRemoteAssist" : true, "commentActions" : true, "approvalActions" : true, "sendReply" : true, "manualDraft" : true, "resolutionActions" : true, "attachmentActions" : true }, "isReviewTime" : "false", "isAutoPause" : "true", "isAutoTimer" : "true", "isHideTimeTracking" : "false" }, "billingType" : "SPECIFIC_COST_PER_AGENT", "activityPreference" : { "isTasksEnabled" : "true", "trackMode" : "CONSECUTIVE", "isEventsEnabled" : "true", "canAutoTrackCalls" : "true" }, "fixedCost" : "1000", "profiles" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ], "depId" : "1892000000006907", "isTimeTracking" : "true", "isBillable" : "true", "agents" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ] }'

TimeTrackingAPI timeTracking = ZDesk.getTimeTrackingAPIInstance(mailId);
TimeTracking timeTrackingObj = new TimeTracking();
timeTrackingObj.setBillingType(billingType);
timeTrackingObj.setTimerAction(timerAction);
TimeTracking response = timeTracking.createTimeTrackingSettings( timeTrackingObj );

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : false,
    "isAutoPause" : true,
    "isAutoTimer" : true,
    "isHideTimeTracking" : false
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : true,
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : true,
    "canAutoTrackCalls" : true
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : true,
  "isBillable" : true,
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

Update TimeTrackSettings

This API updates an existing TimeTracking configuration.

Attributes

Param Name

Data Type

Description

isTimeTracking

boolean

optional

depId

long

optional

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

optional

Key that returns if the time tracked is billable or not.

billingType

String

optional

Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

fixedCost

Double

optional

Cost fixed for either billing category - by ticket or by agent.

agents

list

optional

List of agents in the department

profiles

list

optional

List of user profiles defined in the department

timerAction

String

optional

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

list

optional

Activity preference(s)

ticketPreference

list

optional

Ticket preference(s)

PUT /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/timeTrackSettings
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "ticketPreference" : { "autoTrackAction" : { "fieldUpdate" : true, "onChatComplete" : true, "onRemoteAssist" : true, "commentActions" : true, "approvalActions" : true, "sendReply" : true, "manualDraft" : true, "resolutionActions" : true, "attachmentActions" : true }, "isReviewTime" : "false", "isAutoPause" : "true", "isAutoTimer" : "true", "isHideTimeTracking" : "false" }, "billingType" : "SPECIFIC_COST_PER_AGENT", "activityPreference" : { "isTasksEnabled" : "true", "trackMode" : "CONSECUTIVE", "isEventsEnabled" : "true", "canAutoTrackCalls" : "true" }, "fixedCost" : "1000", "profiles" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ], "depId" : "1892000000006907", "isTimeTracking" : "true", "timerAction" : "ADD", "isBillable" : "true", "agents" : [ { "cost" : "100", "id" : "1" }, { "cost" : "200", "id" : "2" } ] }'

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

Get TimeTrack Settings

This API fetches the details of the TimeTrack Settings configured in your helpdesk.

Query Params

Param Name

Data Type

Description

depId

long

required

ID of the department

GET /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/timeTrackSettings
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TimeTrackingAPI timeTracking = ZDesk.getTimeTrackingAPIInstance(mailId);
TimeTracking response = timeTracking.getTimeTrackSetting(depId );

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

List history details of billing TimeTrack Settings

This API fetches the history of changes made to the billing preferences in time tracking settings. The different events supported are BILLING_PREFERENCE_ENABLED, BILLING_PREFERENCE_DISABLED, BILLING_TYPE_SELECTED, BILLING_TYPE_CHANGED, FIXED_COST_ENTERED, FIXED_COST_EDITED, AGENT_ADDED, AGENT_COST_EDITED, AGENT_DELETED, PROFILE_ADDED, PROFILE_COST_EDITED, and PROFILE_DELETED.

Query Params

Param Name

Data Type

Description

depId

long

required

ID of the department from which the history must be fetched.

from

int

optional

Index number, starting from which the events must be fetched.

limit

int

optional,
range : 1-50

Number of events to be fetched.

include

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/timeTrackHistory

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/timeTrackSettings/history?depId=15000000044059&include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : [ {
      "photoURL" : "'https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20'",
      "name" : "meenakshi"
    } ],
    "modifiedTime" : "2018-02-19T12:53:49.000Z",
    "agentId" : "15000000009148",
    "name" : "AGENT_DELETED",
    "modifiedBy" : "15000000009148"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166891&nps=404&exp=600'",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-19T12:53:49.000Z",
    "agentId" : "15000000009321",
    "cost" : "100",
    "name" : "AGENT_ADDED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    }
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-19T12:45:17.000Z",
    "agentId" : "15000000009148",
    "cost" : "100",
    "name" : "AGENT_ADDED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    }
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "SPECIFIC_COST_PER_AGENT",
    "modifiedTime" : "2018-02-19T12:45:17.000Z",
    "name" : "BILLING_TYPE_CHANGED",
    "modifiedBy" : "15000000009148",
    "oldValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-09T09:09:10.000Z",
    "name" : "BILLING_PREFERENCE_ENABLED",
    "modifiedBy" : "15000000009148"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : null,
    "modifiedTime" : "2018-02-09T09:08:57.000Z",
    "name" : "FIXED_COST_ENTERED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedTime" : "2018-02-09T09:08:57.000Z",
    "name" : "BILLING_TYPE_SELECTED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-09T07:50:01.000Z",
    "name" : "BILLING_PREFERENCE_DISABLED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "1300",
    "modifiedTime" : "2018-02-09T05:13:00.000Z",
    "name" : "FIXED_COST_ENTERED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "FIXED_COST_FOR_AGENTS",
    "modifiedTime" : "2018-02-09T05:13:00.000Z",
    "name" : "BILLING_TYPE_CHANGED",
    "modifiedBy" : "15000000009148",
    "oldValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedAgent" : null
  } ]
}

Views

Views are customized displays of help desk data, which help customer service agents effectively organize their everyday work and deliver better customer service.

List Views

This API lists the different views configured for a specific module or for all modules in your help desk portal. Values allowed are: Tickets, Contacts, Accounts, Tasks, Products, and Contracts.

Query Params

Param Name

Data Type

Description

module
see documentation

string

required,
max chars : 100

Allowed values are : tickets, tasks,contacts, accounts,contacts, products ,activities,calls,events.

departmentId
see documentation

long

optional

Allowed values are : Valid Department Id.

GET /api/v1/views

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/views?module=tickets&departmentId=981212321312321
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CustomViewAPI customView = ZDesk.getCustomViewAPIInstance(mailId);
List<CustomView> response = customView.getViews(module, departmentId );

Response Example

{
  "data" : [ {
    "isCustomView" : false,
    "name" : "All Tasks",
    "id" : "4000000007834"
  }, {
    "isCustomView" : false,
    "name" : "My Tasks",
    "id" : "4000000007836"
  }, {
    "isCustomView" : false,
    "name" : "My Open Tasks",
    "id" : "4000000007838"
  }, {
    "isCustomView" : false,
    "name" : "Completed Tasks",
    "id" : "4000000007840"
  }, {
    "isCustomView" : false,
    "name" : "Open Tasks",
    "id" : "4000000007842"
  }, {
    "isCustomView" : false,
    "name" : "Overdue Tasks",
    "id" : "4000000007844"
  }, {
    "isCustomView" : false,
    "name" : "Todays Tasks",
    "id" : "4000000007846"
  }, {
    "isCustomView" : false,
    "name" : "Tomorrows Tasks",
    "id" : "4000000007848"
  }, {
    "isCustomView" : false,
    "name" : "Today+Overdue Tasks",
    "id" : "4000000007850"
  }, {
    "isCustomView" : false,
    "name" : "Next7days+Overdue Tasks",
    "id" : "4000000007852"
  } ]
}

Add Star View

This API stars a view, enabling quick access to the view.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

POST /api/v1/views/{view_id}/star

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/views/4000000007824/star?departmentId=981212321312321
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Remove Star View

This API unstars a view, disabling quick access to the view.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Allowed values are : Valid Department Id.

POST /api/v1/starredViews/{view_id}/unstar

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/starredViews/4000000007824/unstar?departmentId=981212321312321
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List Starred Views

This API lists the starred views in a module. Number of resources in the starred view is displayed only for the Tickets module.

Query Params

Param Name

Data Type

Description

module
see documentation

string

required,
max chars : 100

Module associated with the view. Values allowed are:tickets, tasks, contacts, accounts, activities, calls or events.

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

GET /api/v1/starredViews

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/starredViews?module=tickets&departmentId=4000000007123
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "starredViews" : [ {
    "isCustomView" : false,
    "name" : "All Tickets",
    "count" : "40",
    "id" : "4000000007834"
  }, {
    "isCustomView" : false,
    "name" : "Open Tickets",
    "count" : "22",
    "id" : "4000000007844"
  } ],
  "module" : "tickets"
}

Starred Views Reorder

This API helps reorder the starred views in a module.

Query Params

Param Name

Data Type

Description

module
see documentation

string

required,
max chars : 100

Module associated with the view. Values allowed are: tickets, tasks, contacts, accounts, contacts, activities, calls or events.

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

Attributes

Param Name

Data Type

Description

starredViewIds

list

required

IDs of the starred views.

PUT /api/v1/starredViews/order

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/starredViews/order?departmentId=981212321312321&module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "starredViewIds" : [ "4000000007808", "4000000007810", "4000000007818", "4000000007820", "4000000007828", "4000000007830", "4000000007848", "4000000007850" ] }'

Response Example

Get Last Accessed View

This API fetches the view last accessed by the user in the module and department specified in the request.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

module

String

required

Module associated with the view. Values allowed are:tickets, tasks, contacts, accounts, activities, calls or events.

GET /api/v1/lastAccessedView

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/lastAccessedView?departmentId=4000000007069&module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : {
    "name" : "My Records",
    "id" : "4000000008143"
  }
}

Update Last Accessed View

This API updates the view last accessed by the user in the module and department specified in the request.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

PUT /api/v1/lastAccessedView/([0-9]+)

OAuth Scope

Desk.basic.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/lastAccessedView/4000000008143?departmentId=4000000007069
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Search

Search helps you find resources in all modules or a specific module in your help desk portal. You can search for multiple resources by separating the values with a comma. Zoho Desk APIs support exact match, wildcard match, empty check and not empty check.

1. Exact match returns resources only if the value passed exactly matches with a resource in the help desk. Wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
2. To perform a multiple character wildcard match, append an asterisk (*) after the value to search.
3. If you want the search to return resources that do not have a value in a particular field, pass the value of the corresponding query parameter as ${empty} in the API request.
4. If you want the search to return resources with any value in a particular field, pass the value of the corresponding query parameter as ${notempty} in the API request.
5. Both ${empty} and ${notEmpty} should be urlEncoded.

Note:
1. Query parameters, especially those of string type, pertaining to search APIs must be URL-encoded.
2. New resources that you add to your help desk might take some time to be indexed for search. Therefore, if the resources do not appear in search results, wait for a few minutes and try again.
3. At least 3 characters are required in the search string for a successful search.
4. To search status mapped tickets use ${OPEN},${ONHOLD},${CLOSED} respectively for open, onhold and closed status mapping
5. Wildcard match is supported only for fields of string type. To perform a wildcard match, append an asterisk () after the search keyword. For example, doc returns doc and document in the search results, but not donation.
6. Appending an asterisk (*) at the beginning or middle of the search keyword does not provide any results.
7. In the case of mobile and phone fields, wildcard match works even if the asterisk (*) is appended at the beginning of the search keyword.
8. The sortBy=relevance key-attribute pair fetches the most relevant records first.
9. sortBy=-modifiedTime, A - prefix denotes a descending order of sorting.
10. Each search can return only a maximum of 5,000 resources. To fetch more resources, write your program such that the search results are filtered based on the TimeRange parameter.
Example:
A month time range in modifiedTime field
https://desk.zoho.com/api/v1/tickets/search?limit=100&from=0&sortBy=modifiedTime&modifiedTimeRange=2018-01-01T00:00:00.000Z,2019-01-31T23:59:59.000Z

Search across modules

This API returns information from all modules or a specific module, based on the value of the module query param.

Query Params

Param Name

Data Type

Description

searchStr

String

optional

Keyword or phrase to search

module

String

optional

Module to search in: tickets, accounts, contacts or tasks. The default response includes all modules.

departmentId

long

optional

ID of the department from which the resource must be fetched

from

int

optional,
default : 0,
range : 0-4999

Index number, starting from which the resources must be searched

limit

int

optional,
default : 10,
range : 1-5000

Number of resources to return in the search result

sortBy

String

optional

Sort by a specific attribute: relevance or modifiedTime

GET /api/v1/search?searchStr={searchStr}&departmentId={departmentId}&from={from}&limit={limit}&sortBy={sortField}

OAuth Scope

Desk.search.READ , Desk.tickets.READ , Desk.contacts.READ , Desk.tasks.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/search?searchStr=zylker&from=0&limit=10&sortBy=modifiedTime
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "subject" : "Zylker ticket",
    "departmentId" : "4000000007043",
    "dueDate" : null,
    "channel" : "Phone",
    "onholdTime" : null,
    "sharedDepartments" : [ ],
    "closedTime" : null,
    "number" : "104",
    "contact" : {
      "phone" : null,
      "mobile" : "9876543210",
      "name" : "Stephen",
      "id" : "4000000013012",
      "type" : null,
      "email" : null,
      "account" : {
        "website" : null,
        "name" : "Zylker Accounts",
        "id" : "4000000008850"
      }
    },
    "createdTime" : "2016-06-27T07:22:52.000Z",
    "id" : "4000000016009",
    "department" : {
      "name" : "Testing",
      "id" : "4000000007043"
    },
    "email" : null,
    "customerResponseTime" : "2016-06-27T07:22:52.117Z",
    "cf" : {
      "cf_featureRequest" : false,
      "cf_region" : "Asia"
    },
    "productId" : "4000000013043",
    "contactId" : "4000000013012",
    "module" : "tickets",
    "threadCount" : "0",
    "team" : {
      "name" : "TestingTeam",
      "id" : "4000000007235"
    },
    "priority" : null,
    "assigneeId" : "4000000008692",
    "commentCount" : "0",
    "phone" : null,
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "4000000008692",
      "zuid" : "10657727"
    },
    "status" : "Open"
  }, {
    "cf" : {
      "cf_followUpDate" : "2016-07-07T19:30:00.000Z",
      "cf_severity" : "High"
    },
    "ticket" : null,
    "subject" : "Wifi adapter not working in zylker",
    "completedTime" : null,
    "module" : "tasks",
    "dueDate" : "2016-06-27T19:30:00.000Z",
    "description" : null,
    "ownerId" : "4000000008692",
    "priority" : "High",
    "isCommented" : false,
    "createdBy" : "4000000008692",
    "contact" : null,
    "createdTime" : "2016-06-27T06:39:48.000Z",
    "id" : "4000000013065",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "category" : null,
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "ticketId" : null,
    "status" : "Not Started"
  }, {
    "website" : null,
    "phone" : null,
    "accountName" : "Zylker India",
    "customFields" : {
      "city" : "Delhi",
      "state" : "India"
    },
    "module" : "accounts",
    "id" : "4000000013027",
    "email" : null
  }, {
    "lastName" : "Stephen",
    "accountId" : "4000000008850",
    "firstName" : "Henry",
    "photoURL" : null,
    "phone" : null,
    "customFields" : {
      "customerSince" : "2011",
      "editionUsed" : "Professional"
    },
    "module" : "contacts",
    "fullName" : "Henry Stephen",
    "id" : "4000000013012",
    "ownerId" : "4000000008692",
    "email" : null,
    "account" : {
      "website" : null,
      "name" : "Zylker India",
      "id" : "4000000008850"
    }
  } ],
  "count" : {
    "tickets" : 1,
    "accounts" : 1,
    "tasks" : 1,
    "contacts" : 1
  }
}

Tickets Search API

This API searches for tickets in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.

Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

CustomField param Example:
customField1=cf_modelName:F3*
customField2=cf_phone:902*
customField3=cf_permanentAddress: Wall Street*

Note:
wildcard match will not be available for the custom fields that are not of type string
Wildcard character question mark (?) is not supported
mobile and phone fields supports asterisk (*) at the beginning

Urlencoded Example:
customField1=cf_modelName%3AF3*
customField2=cf_phone%3A902*
customField3=cf_permanentAddress%3AWall%20Street*
For empty check: email=%24%7Bempty%7D

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

departmentId

long

optional

ID of the department from which the entity must be fetched. if not passed then searches in permitted departments
exact match

long

optional

ID of the ticket
exact match

ticketNumber

String

optional

Serial number of the ticket in the help desk
exact match

subject

String

optional

subject of the ticket in the help desk
wildcard search

description

String

optional

description of the ticket in the help desk
wildcard search

status

String

optional

Status of the ticket. Includes the custom statuses that exist in your help desk
exact match

priority

String

optional

Priority of the ticket
exact match

String

optional

Email ID in the ticket
wildcard search

empty check

not empty check

phone

String

optional

Phone number in the ticket
wildcard search

empty check

not empty check

channel

String

optional

Channel through which the ticket was received
exact match

empty check

not empty check

category

String

optional

Category in the ticket
wildcard search

empty check

not empty check

assigneeId

long

optional

ID of the agent assigned to resolve the ticket
exact match

contactId

long

optional

ID of the contact who raised the ticket
exact match

accountId

long

optional

ID of the account associated with the ticket
exact match

productId

long

optional

ID of the product associated with the ticket
exact match

contactName

String

optional

Name of the contact who raised the ticket
wildcard search

accountName

String

optional

Name of the account associated with the ticket
wildcard search

empty check

not empty check

productName

String

optional

Name of the product associated with the ticket
wildcard search

empty check

not empty check

tag

String

optional

Tag in the ticket
wildcard search

empty check

not empty check

_all

String

optional

Search throughout the ticket
wildcard search

customField1

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField2

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField3

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the ticket
wildcard search

empty check

not empty check

customerResponseTimeRange

timestamp

optional

Key that filters tickets in which customer responses were recorded in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, customerResponseTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z2017-11-05T13:15:30.000Z,2018-09-05T13:15:30.000Z

createdTimeRange

timestamp

optional

Key that filters tickets created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters tickets modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

dueDateRange

timestamp

optional

Key that filters tickets due in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, dueDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

customerResponseTime

GET /api/v1/tickets/search

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/search?limit=1&subject=analysis*
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

SearchAPI search = ZDesk.getSearchAPIInstance(mailId);
SearchTicketsFilter filter = new SearchTicketsFilter.Builder().setCustomField5(customField5).build();
List<Ticket> response = search.searchTickets( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-06-21T13:16:14.000Z",
    "ticketNumber" : "101",
    "subCategory" : "Sub General",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "isRead" : false,
    "channel" : "FORUMS",
    "onholdTime" : null,
    "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "resolution" : null,
    "sharedDepartments" : [ {
      "name" : "Sample Department Name",
      "id" : "1892000000006909",
      "type" : "READ_WRITE"
    }, {
      "name" : "Sample Department Name",
      "id" : "1892000000006911",
      "type" : "READ_ONLY"
    } ],
    "closedTime" : null,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543456",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "modifiedBy" : "52338000000043001",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "product" : null,
    "cf" : {
      "cf_permanentaddress" : null,
      "cf_dateofpurchase" : null,
      "cf_phone" : null,
      "cf_numberofitems" : null,
      "cf_url" : null,
      "cf_secondaryemail" : null,
      "cf_severitypercentage" : "0.0",
      "cf_modelname" : "F3 2017"
    },
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "lastThread" : {
      "channel" : "FEEDBACK",
      "isDraft" : false,
      "isForward" : false,
      "direction" : "in"
    },
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "classification" : null,
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : "1 888 900 9646",
    "createdBy" : "52338000000043001",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "emailId" : "jack@asdad.com",
      "id" : "1892000000056007",
      "zuid" : "640954748"
    },
    "category" : "general",
    "status" : "Open"
  } ],
  "count" : 1
}

Search accounts

This API searches for accounts in your help desk portal.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

long

optional

ID of the account
exact match

accountName

String

optional

Name of the account
wildcard search

_all

String

optional

Search throughout the account
wildcard search

customField1

String

optional

Custom field in the account
wildcard search
e.g customField1=cf_activeAccount:true
empty check
e.g customField1=cf_activeAccount:${empty}
not empty check

customField2

String

optional

Custom field in the account
wildcard search

empty check

not empty check
e.g customField2=cf_activeAccount:${notempty}

customField3

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the account
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the account
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters accounts created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters accounts modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

accountName

GET /api/v1/accounts/search

OAuth Scope

Desk.search.READ , Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/search?limit=1&accountName=Zylker
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

SearchAPI search = ZDesk.getSearchAPIInstance(mailId);
SearchAccountsFilter filter = new SearchAccountsFilter.Builder().setCustomField5(customField5).build();
List<Account> response = search.searchAccounts( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Twin",
      "lastName" : "john",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/52338000000691001/photo?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "3263000000057001",
      "zuid" : "10657727"
    },
    "country" : "USA",
    "modifiedTime" : "2015-03-02T14:49:18.000Z",
    "website" : "www.zylker.com",
    "code" : "3211",
    "cf" : {
      "cf_contactcount" : "1"
    },
    "accountName" : "Zylker",
    "city" : null,
    "description" : null,
    "industry" : "Automation",
    "ownerId" : "3263000000057001",
    "phone" : "6218129190",
    "street" : null,
    "annualrevenue" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "state" : null,
    "id" : "3263000000074571",
    "fax" : "+1 444 8656 8732",
    "email" : "support@zylker.com"
  } ],
  "count" : 1
}

Search Contacts

This API searches for contacts in your help desk portal.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

long

optional

ID of the contact
exact match

fullName

String

optional

Full name of the contact
wildcard search

firstName

String

optional

First name of the contact
wildcard search

empty check

not empty check

lastName

String

optional

Last name of the contact
wildcard search

String

optional

Email ID of the contact
wildcard search

empty check

not empty check

phone

String

optional

Phone number of the contact
wildcard search

empty check

not empty check

mobile

String

optional

Mobile number of the contact
wildcard search

empty check

not empty check

accountName

String

optional

Name of the account associated with the Contact
wildcard search

empty check

not empty check

_all

String

optional

Search throughout the contact
wildcard search

customField1

String

optional

Custom field in the Contact
wildcard search
e.g customField1=cf_mappedWithAccount:true
empty check
e.g customField1=cf_mappedWithAccount:${empty}
not empty check

customField2

String

optional

Custom field in the contact
wildcard search

empty check

not empty check
e.g customField2=cf_mappedWithAccount:${notempty}

customField3

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the contact
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters contacts created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters contacts modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

lastName,

firstName

GET /api/v1/contacts/search

OAuth Scope

Desk.search.READ , Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/search?limit=1&lastName=Lawrence
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

SearchAPI search = ZDesk.getSearchAPIInstance(mailId);
SearchContactsFilter filter = new SearchContactsFilter.Builder().setCustomField5(customField5).build();
List<Contact> response = search.searchContacts( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "lastName" : "Lawrence",
    "modifiedTime" : "2016-05-04T09:57:17.000Z",
    "country" : null,
    "secondaryEmail" : null,
    "city" : null,
    "description" : null,
    "ownerId" : "1892000000042001",
    "type" : null,
    "title" : null,
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
    "twitter" : null,
    "street" : null,
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "isEndUser" : "false",
    "zohoCRMContact" : {
      "id" : "5000000014010",
      "type" : "contacts_leads"
    },
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "state" : null,
    "id" : "1892000000042032",
    "email" : "lawrence@zylker.com",
    "zip" : null,
    "owner" : {
      "firstName" : "Twin",
      "lastName" : "john",
      "photoURL" : null,
      "emailId" : "lawrence@zylker.com",
      "id" : "1892000000042001",
      "zuid" : "14345345"
    },
    "cf" : {
      "cf_permanentaddress" : null,
      "cf_lastcontactedon" : null
    },
    "facebook" : null,
    "mobile" : null,
    "accountId" : "1892000000975382",
    "firstName" : "Jennifer",
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "account" : {
      "website" : null,
      "accountName" : "Zylker",
      "id" : "1892000000975382"
    }
  } ],
  "count" : 1
}

Article Search API

This API searches for help articles in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

departmentId

long

optional

ID of the department from which the entity must be fetched. if not passed then searches in permitted departments
exact match

long

optional

ID of the articles
exact match

title

String

optional

title of the help article
wildcard search

categoryName

String

optional

Name of the Category
wildcard search

categoryId

long

optional

ID of the Category

tag

String

optional

Tag in the articles
wildcard search

empty check

not empty check

_all

String

optional

Key that includes all article details for the search
wildcard search

createdTimeRange

timestamp

optional

Key that filters articles created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters articles modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime

GET /api/v1/articles/search

OAuth Scope

Desk.search.READ , Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/search?limit=1&title=Knowledge
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
    "modifiedTime" : "2018-07-16T06:48:08.000Z",
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : null,
      "name" : "HIll",
      "id" : "5000000015935"
    },
    "creatorId" : "4000000012931",
    "modifierId" : "4000000012931",
    "dislikeCount" : "1",
    "permission" : "AGENTS",
    "likeCount" : "2",
    "title" : "Importance of a Knowledge Base",
    "authorId" : "4000000012931",
    "usageCount" : "3",
    "latestVersion" : "1.0",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000281023",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-knowledge-base",
    "feedbackCount" : "1",
    "createdTime" : "2018-07-16T06:48:08.000Z",
    "latestPublishedVersion" : "1.0",
    "viewCount" : "3",
    "id" : "22372000000281023",
    "permalink" : "importance-of-a-knowledge-base",
    "category" : {
      "name" : "General",
      "id" : "5000000017008"
    },
    "categoryId" : "4000000013240",
    "status" : "Published"
  } ],
  "count" : 379
}

Search Tasks

This API searches for tasks in your help desk portal.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

departmentId

long

optional

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

long

optional

ID of the task
exact match

subject

String

optional

subject of the task in the help desk
wildcard search

ticketNumber

String

optional

ticket Number of the ticket that associated with the task
exact match

status

String

optional

status of the task
exact match

priority

String

optional

Priority of the task
exact match

assigneeId

long

optional

ID of the agent assigned to resolve the task
exact match

_all

String

optional

Search throughout the task
wildcard search

customField1

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField2

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField3

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the task
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the task
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters tasks created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters tasks modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

dueDateRange

timestamp

optional

Key that filters tasks due in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, dueDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

GET /api/v1/tasks/search

OAuth Scope

Desk.search.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/search?limit=1&priority=High,Low
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

SearchAPI search = ZDesk.getSearchAPIInstance(mailId);
SearchTasksFilter filter = new SearchTasksFilter.Builder().setCustomField5(customField5).build();
List<Task> response = search.searchTasks( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-09-13T12:14:41.000Z",
    "cf" : {
    },
    "ticket" : null,
    "subject" : "Bug Fix #121",
    "completedTime" : null,
    "departmentId" : "3000000007043",
    "dueDate" : "2016-09-19T12:27:26.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "3000000054002",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2016-08-14T08:27:26.000Z",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "id" : "3000000054004",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ],
  "count" : 1
}

Call Search API

This API searches for calls in your help desk portal. You can pass multiple values by separating them with commas, which denotes the search on the field is done using any of the values passed.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

Index number, starting from which the calls must be fetched. for example, from=0

limit

int

optional,
default : 10,
range : 1-100

Number of calls to fetch

departmentId

long

optional

ID of the department from which the call must be fetched. If a valid ID is not passed, the search is performed in all departments permitted.
exact match

long

optional

ID of the call
exact match

subject

String

optional

subject of the call
wildcard search

ticketNumber

String

optional

Ticket number of the ticket associated with the call
exact match

status

String

optional

Status of the call
exact match

priority

String

optional

Priority of the call
exact match

assigneeId

long

optional

ID of the agent assigned to handle the call
exact match

_all

String

optional

Key that includes all call details for the search
wildcard search

customField1

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField2

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField3

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the call
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the call
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters calls recorded in the help desk in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters calls whose details were modified in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

startDateRange

timestamp

optional

Key that filters calls that were made in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, startDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

GET /api/v1/calls/search

OAuth Scope

Desk.search.READ , Desk.calls.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/calls/search?limit=1&priority=High,Low
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-26T17:32:11.000Z",
    "ticket" : {
      "ticketNumber" : "101",
      "contact" : {
        "firstName" : null,
        "lastName" : "Lawrence",
        "phoneNumber" : "+14246721666",
        "id" : "3000000008749"
      },
      "id" : "3000000008753"
    },
    "customFields" : {
    },
    "subject" : "New Call",
    "completedTime" : "2016-07-26T17:32:11.000Z",
    "departmentId" : "3000000007043",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : null,
    "priority" : "Normal",
    "duration" : "300",
    "createdTime" : "2016-07-26T17:32:11.000Z",
    "startTime" : "2016-07-25T16:52:11.000Z",
    "id" : "3000000018001",
    "assignee" : {
      "firstName" : "",
      "lastName" : "raja",
      "photoURL" : null,
      "emailId" : "rajasekaran.r+activitydisabled@zohocorp.com",
      "id" : "36385000000120033",
      "zuid" : "55499215"
    },
    "ticketId" : "3000000008753",
    "direction" : "inbound",
    "status" : "completed"
  } ],
  "count" : 1
}

Event Search API

This API searches for events in your help desk portal. You can pass multiple values by separating them with commas, which denotes the search on the field is done using any of the values passed.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

Index number, starting from which the events must be fetched, starts from 0

limit

int

optional,
default : 10,
range : 1-100

Number of events to fetch

departmentId

long

optional

ID of the department from which the event must be fetched. If a valid ID is not passed, the search is performed in all departments permitted.
exact match

long

optional

ID of the event
exact match

subject

String

optional

Subject of the event
wildcard search

ticketNumber

String

optional

Ticket number of the ticket associated with the event
exact match

status

String

optional

Status of the event
exact match

priority

String

optional

Priority of the event
exact match

assigneeId

long

optional

ID of the agent assigned to handle the event
exact match

_all

String

optional

Key that includes all event details for the search
wildcard search

customField1

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField2

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField3

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the event
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the event
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters events recorded in the help desk in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters events whose details were modified in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

startDateRange

timestamp

optional

Key that filters events that occurred in a particular period. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, startDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

GET /api/v1/events/search

OAuth Scope

Desk.search.READ , Desk.events.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/events/search?limit=1&priority=High,Low
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-26T17:32:11.000Z",
    "ticket" : {
      "ticketNumber" : "101",
      "contact" : {
        "firstName" : null,
        "lastName" : "Lawrence",
        "id" : "3000000008749"
      },
      "id" : "3000000008753"
    },
    "customFields" : {
    },
    "subject" : "New Event",
    "completedTime" : "2016-07-26T17:32:11.000Z",
    "departmentId" : "3000000007043",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : null,
    "priority" : "Normal",
    "duration" : "30",
    "createdTime" : "2016-07-26T16:32:11.000Z",
    "startTime" : "2016-07-26T17:02:11.000Z",
    "id" : "3000000018001",
    "assignee" : {
      "firstName" : "",
      "lastName" : "raja",
      "photoURL" : null,
      "emailId" : "rajasekaran.r+activitydisabled@zohocorp.com",
      "id" : "36385000000120033",
      "zuid" : "55499215"
    },
    "category" : "Meeting",
    "ticketId" : "3000000008753",
    "status" : "completed"
  } ],
  "count" : 1
}

Products Search API

This API searches for products in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

From index, starts from 0

limit

int

optional,
default : 10,
range : 1-100

No. of entities to fetch

departmentId

long

optional

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

long

optional

ID of the Product
exact match

productName

String

optional

Name of the Product
wildcard search

productCode

String

optional

Code of the product
wildcard search

empty check

not empty check

contactId

long

optional

ID of the contact associated with the product
exact match

accountId

long

optional

ID of the account associated with the product
exact match

_all

String

optional

Search throughout the product
wildcard search

customField1

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField2

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField3

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField4

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField5

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField6

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField7

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField8

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField9

String

optional

Custom field in the product
wildcard search

empty check

not empty check

customField10

String

optional

Custom field in the product
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters products created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Key that filters products modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

productName

GET /api/v1/products/search

OAuth Scope

Desk.search.READ , Desk.products.READ , ~~Desk.settings.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/search?limit=1&productName=Search2
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

SearchAPI search = ZDesk.getSearchAPIInstance(mailId);
SearchProductsFilter filter = new SearchProductsFilter.Builder().setCustomField5(customField5).build();
List<Product> response = search.searchProducts( from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-11-02T10:31:35.000Z",
    "productCode" : "Search2",
    "cf" : {
      "cf_productTagName" : null
    },
    "createdBy" : "5000000009116",
    "description" : null,
    "createdTime" : "2017-11-02T10:31:35.000Z",
    "modifiedBy" : "5000000009116",
    "departmentIds" : [ "5000000007235" ],
    "id" : "5000000009882",
    "productName" : "Search2"
  } ],
  "count" : 1
}

Search Activities

This API searches for activities in your help desk portal.

Query Params

Param Name

Data Type

Description

from

int

optional,
default : 0,
range : 0-4999

Index number, starting from which the activities must be fetched, starts from 0

limit

int

optional,
default : 10,
range : 1-100

Number of activities to list

departmentId

long

optional

ID of the department from which the activity must be fetched. If you do not pass a value for this parameter, the search is performed in all permitted departments.
exact match

long

optional

ID of the activity
exact match

subject

String

optional

Subject of the activity
wildcard search

ticketNumber

String

optional

Serial number of the ticket associated with the activity
exact match

status

String

optional

Completion status of the activity
exact match

priority

String

optional

Priority of the activity
exact match

assigneeId

long

optional

ID of the agent assigned to handle the activity
exact match

_all

String

optional

Key that searches across all fields in all activities
wildcard search

createdTimeRange

timestamp

optional

Key that filters activities created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.

modifiedTimeRange

timestamp

optional

Key that filters activities whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

GET /api/v1/activities/search

OAuth Scope

Desk.search.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.calls.READ~~ , ~~Desk.tasks.READ~~ , ~~Desk.events.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/activities/search?limit=1&priority=High,Low
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-09-13T12:14:41.000Z",
    "ticket" : null,
    "customFields" : {
    },
    "subject" : "Bug Fix #121",
    "completedTime" : null,
    "module" : "task",
    "departmentId" : "3000000007043",
    "dueDate" : "2016-09-19T12:27:26.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "3000000054002",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2016-08-14T08:27:26.000Z",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "id" : "3000000054004",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ],
  "count" : 1
}

Ticket TimeEntry

Ticket time entry refers to the time taken by an agent to resolve a ticket.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

show Attributes

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

~~customFields~~

deprecated

list

User-defined fields related to the time entry.

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

String

Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

invoiceId

long

ID of the invoice related to the time entry

Example

{ "owner" : { "firstName" : "Eswer", "lastName" : "KM", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Eswer KM", "id" : "4000000008688129" }, "secondsSpent" : "0", "parent" : { "subject" : "Ticket subject", "id" : "4000000031007", "type" : "TICKETS" }, "cf" : { }, "executedTime" : null, "departmentId" : "4000000008694", "fixedCost" : null, "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "isBillable" : true, "mode" : "MANUAL", "isTrashed" : "false", "billingType" : "FIXED_COST_FOR_TICKETS", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "4000000008688123", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }

Get Ticket Time Entry

This API fetches a time entry recorded for a ticket.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000033010?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "parent" : {
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "secondsSpent" : "21",
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "departmentId" : "4000000008694",
  "fixedCost" : null,
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Ticket Time Entries

This API lists the time entries associated with a ticket.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key that filters time entries created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.

modifiedTimeRange

timestamp

optional

Key that filters time entries whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.

GET /api/v1/tickets/{ticket_id}/timeEntry

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry?from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time2"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "departmentId" : "4000000008694",
    "fixedCost" : null,
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time3"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add Ticket Time Entry

This API adds a time entry in your help desk

Attributes

Param Name

Data Type

Description

requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

required

Time when work related to the time entry was started.

hoursSpent

integer

optional

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

~~customFields~~

deprecated

list

optional

User-defined fields related to the time entry.

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

POST /api/v1/tickets/{ticket_id}/timeEntry

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "secondsSpent" : "21", "cf" : { "cf_timeentryname" : "time2" }, "executedTime" : "2016-06-22T20:30:00.000Z", "minutesSpent" : "23", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "invoiceId" : "4000000008688123", "ownerId" : "4000000008692", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update Ticket Time Entry

This API updates an existing ticket time entry

Attributes

Param Name

Data Type

Description

requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

optional

Time when work related to the time entry was started.

hoursSpent

integer

optional

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

~~customFields~~

deprecated

list

optional

User-defined fields related to the time entry.

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

PATCH /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "description" : "Time Entry description", "requestChargeType" : "Customer Service" }'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000031007",
    "subject" : "Task subject",
    "id" : "4000000031008",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete Ticket Time Entry

This API deletes a time entry recorded for a ticket

DELETE /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get summation of Ticket Time Entries

This API fetches the sum of time entries associated with a ticket.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/tickets/{ticket_id}/timeEntrySummation

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntrySummation?billStatus=billed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Get Ticket Time Entries by Billing Type

This API fetches time entries for a ticket created after recently modified time of the given billing type from your help desk

Query Params

Param Name

Data Type

Description

billingType

String

required

Allowed values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT SPECIFIC_COST_PER_PROFILE

include
see documentation

string

optional,
max chars : 100

Allowed value is : owner

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

GET /api/v1/tickets/{ticket_id}/timeEntryByBillingType

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntryByBillingType?billingType=FIXED_COST_FOR_TICKETS&include=owner&from=0&limit=10
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "0",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
    },
    "executedTime" : null,
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "0",
    "agentCostPerHour" : null,
    "description" : null,
    "hoursSpent" : "0",
    "ownerId" : "15000000009148",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "createdBy" : "15000000009148",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2018-01-10T18:45:17.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "15000000031007",
    "requestChargeType" : "Customer Service",
    "additionalCost" : null,
    "totalCost" : "0.0"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "0",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
    },
    "executedTime" : "2017-12-20T18:09:20.000Z",
    "departmentId" : "4000000008694",
    "fixedCost" : null,
    "minutesSpent" : "0",
    "agentCostPerHour" : null,
    "description" : "Dummy#2",
    "hoursSpent" : "1",
    "ownerId" : "15000000009148",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "createdBy" : "15000000009148",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2018-01-10T15:20:47.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "15000000029314",
    "requestChargeType" : "Upgrade Request",
    "additionalCost" : null,
    "totalCost" : "0.0"
  } ]
}

Ticket Approvals

Often, customer support agents do not have the authority to make decisions related to ticket resolution. When the intervention of a support manager or any other higher authority is required in the decision-making process, the agent can submit the ticket for approval.

ATTRIBUTES

Attribute Name

Data Type

Description

approverIds

list

IDs of users to whom the approval must be submitted

subject

string

Subject of the approval

status

string

Status of the approval

description

String

Description of the approval

requestedTime

timestamp

Time when the approval was requested

processedTime

timestamp

Time when the approval was processed

long

ID of the approval

requester

show Attributes

object

Details of user who requested for the approval

approver

show Attributes

object

Details of user who processed the approval

Example

{ "approver" : { "firstName" : "", "lastName" : "Saranraj", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000013292/photo", "id" : "5000000013292", "email" : null }, "requester" : { "firstName" : "", "lastName" : "Smith", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo", "id" : "5000000012902", "email" : null }, "requestedTime" : "2018-06-18T14:22:21.871Z", "subject" : "saran test approval", "description" : "", "id" : "5000000026001", "status" : "Pending", "processedTime" : null }

List approvals

This API lists the approvals submitted in your help desk.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number starting from which the approvals must be fetched

limit

integer

optional,
range : 1-100

Number of approvals to fetch

status

string

optional,
max chars : 100

Key that filters the approvals by status

GET /api/v1/tickets/{ticket_id}/approvals

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "approver" : {
      "firstName" : "",
      "lastName" : "raj",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
      "id" : "4000000015001",
      "email" : "saran@zohocorp.com"
    },
    "requester" : {
      "firstName" : "",
      "lastName" : "saran",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
      "id" : "4000000012629",
      "email" : "saranraj@zoho.com"
    },
    "requestedTime" : "2016-06-21T13:16:14.000Z",
    "subject" : "Testing",
    "description" : "testing",
    "id" : "1892000001054081",
    "status" : "Approved",
    "processedTime" : "2018-02-07T10:12:35.000Z"
  } ]
}

Get approval

This API fetches the details of an approval.

GET /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals/1892000001054081
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "approver" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
    "id" : "4000000015001",
    "email" : null
  },
  "requester" : {
    "firstName" : "aravind",
    "lastName" : "a",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
    "id" : "4000000012629",
    "email" : null
  },
  "requestedTime" : "2016-06-21T13:16:14.000Z",
  "subject" : "Testing",
  "processedTime " : "2018-02-07T10:12:35.000Z",
  "description" : "testing",
  "id" : "1892000001054081",
  "status" : "Rejected"
}

Create approval

This API creates an approval in your help desk.

Attributes

Param Name

Data Type

Description

approverIds

list

required

IDs of users to whom the approval must be submitted

subject

string

required,
max chars : 1000

Subject of the approval

status

string

optional,
max chars : 100

Status of the approval

description

String

optional

Description of the approval

POST /api/v1/tickets/{ticket_id}/approvals

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "approverIds" : [ "1892000000042001" ],
  "subject" : "New approval",
  "description" : "new app desc"
}'

Response Example

{
  "approvals" : [ {
    "approver" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
      "id" : "4000000015001",
      "email" : null
    },
    "requester" : {
      "firstName" : "aravind",
      "lastName" : "a",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
      "id" : "4000000012629",
      "email" : null
    },
    "requestedTime" : "2016-06-21T13:16:14.000Z",
    "subject" : "Testing",
    "description" : "testing",
    "id" : "1892000001054081",
    "status" : "PENDING",
    "processedTime" : null
  } ]
}

Update approval

This API updates the details of an existing ticket approval.

Attributes

Param Name

Data Type

Description

approverIds

list

optional

IDs of users to whom the approval must be submitted

subject

string

optional,
max chars : 1000

Subject of the approval

status

string

optional,
max chars : 100

Status of the approval

description

String

optional

Description of the approval

PATCH /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals/1892000001054081
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "status" : "Approved/Rejected"
}'

Response Example

{
  "approver" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
    "id" : "4000000015001",
    "email" : null
  },
  "requester" : {
    "firstName" : "aravind",
    "lastName" : "a",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
    "id" : "4000000012629",
    "email" : null
  },
  "requesterId" : "1892000000042001",
  "requestedTime" : "2016-06-21T13:16:14.000Z",
  "approverId" : "1892000000042001",
  "subject" : "Testing",
  "description" : "testing",
  "id" : "1892000001054081",
  "status" : "Approved",
  "processedTime" : "2018-02-07T10:12:35.000Z"
}

Task TimeEntry

Tasks Time Entry refers to the time taken by an agent to complete a task.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

show Attributes

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

~~customFields~~

deprecated

list

User-defined fields related to the time entry.

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

String

Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

invoiceId

long

ID of the invoice related to the time entry

Example

{ "owner" : { "firstName" : "Eswer", "lastName" : "KM", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Eswer KM", "id" : "4000000008688129" }, "secondsSpent" : "0", "parent" : { "associatedTicketId" : "4000000030017", "subject" : "Tasks subject", "id" : "4000000031014", "type" : "TASKS" }, "cf" : { }, "executedTime" : null, "fixedCost" : null, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "isBillable" : true, "mode" : "MANUAL", "isTrashed" : "false", "billingType" : "FIXED_COST_FOR_TICKETS", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "40000000086881212", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }

Get a Task Time Entry

This API fetches a time entry recorded for a task.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000033010?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "departmentId" : "4000000008694",
  "fixedCost" : null,
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Task Time Entries

This API lists the time entries associated with a task.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

GET /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry?from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time2"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time3"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add a Task Time Entry

This API creates a time entry in your help desk

Attributes

Param Name

Data Type

Description

requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

required

Time when work related to the time entry was started.

hoursSpent

integer

optional

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

~~customFields~~

deprecated

list

optional

User-defined fields related to the time entry.

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

POST /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.activities.CREATE , Desk.activities.tasks.CREATE , ~~Desk.tasks.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "secondsSpent" : "21", "cf" : { "cf_timeentryname" : "time2" }, "executedTime" : "2016-06-22T20:30:00.000Z", "minutesSpent" : "23", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update a Task Time Entry

This API updates details of an existing time entry.

Attributes

Param Name

Data Type

Description

requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

optional

Time when work related to the time entry was started.

hoursSpent

integer

optional

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

~~customFields~~

deprecated

list

optional

User-defined fields related to the time entry.

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

PATCH /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000034008
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "description" : "Time Entry description", "requestChargeType" : "Customer Service" }'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete a Task Time Entry

This API deletes a time entry recorded for a task.

DELETE /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000034008
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get summation of Task Time Entries

This API fetches the sum of time entries associated with a task.

Query Params

Param Name

Data Type

Description

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/tasks/{task_id}/timeEntrySummation

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntrySummation?billStatus=billed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Agent TimeEntry

Agent time entry refers to the time taken by an agent to resolve a ticket or perform a task.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

show Attributes

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

~~customFields~~

deprecated

list

User-defined fields related to the time entry.

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

String

Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

invoiceId

long

ID of the invoice related to the time entry

Example

{ "owner" : { "firstName" : "Eswer", "lastName" : "KM", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Eswer KM", "id" : "4000000008688129" }, "secondsSpent" : "0", "parent" : { "subject" : "Ticket subject", "id" : "4000000031007", "type" : "TICKETS" }, "cf" : { }, "executedTime" : null, "fixedCost" : null, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "isBillable" : true, "mode" : "MANUAL", "isTrashed" : "false", "billingType" : "FIXED_COST_FOR_TICKETS", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "40000000086881212", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }

Get an Agent Time Entry

This API fetches a time entry related to an agent.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/agents/{agent_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntry/4000000033010?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000031007",
    "subject" : "Task subject",
    "id" : "4000000031010",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Agent Time Entries

This API lists the time entries associated with an agent.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

GET /api/v1/agents/{agent_id}/timeEntry

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Agent Time Entries

This API fetches the sum of time entries associated with an agent.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/agents/{agent_id}/timeEntrySummation

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Contact TimeEntry

Contact time entry refers to the time taken to resolve a ticket or perform a task related to a particular contact.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

show Attributes

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

~~customFields~~

deprecated

list

User-defined fields related to the time entry.

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

String

Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

invoiceId

long

ID of the invoice related to the time entry

Example

{ "owner" : { "firstName" : "Eswer", "lastName" : "KM", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Eswer KM", "id" : "4000000008688129" }, "secondsSpent" : "0", "parent" : { "subject" : "Ticket subject", "id" : "4000000031007", "type" : "TICKETS" }, "cf" : { }, "executedTime" : null, "fixedCost" : null, "departmentId" : "4000000008694", "minutesSpent" : "0", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "isBillable" : true, "mode" : "MANUAL", "isTrashed" : "false", "billingType" : "FIXED_COST_FOR_TICKETS", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "40000000086881212", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }

List Contact Time Entries

This API lists time entries recorded for a ticket or task related to a contact.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched.

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

GET /api/v1/contacts/{contact_id}/timeEntry

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "associatedTicketId" : "4000000031014",
      "subject" : "Tasks subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Contact Time Entries

This API fetches summation of time entries for a contact from your help desk

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/contacts/{contact_id}/timeEntrySummation

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Account TimeEntry

Account time entry refers to the time taken to resolve a ticket or perform a task related to a particular account.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

show Attributes

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

~~customFields~~

deprecated

list

User-defined fields related to the time entry.

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

String

Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

invoiceId

long

ID of the invoice related to the time entry

Example

{ "owner" : { "firstName" : "Eswer", "lastName" : "KM", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Eswer KM", "id" : "4000000008688129" }, "secondsSpent" : "0", "parent" : { "subject" : "Ticket subject", "id" : "4000000031007", "type" : "TICKETS" }, "cf" : { }, "executedTime" : null, "fixedCost" : null, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "isBillable" : true, "mode" : "MANUAL", "isTrashed" : "false", "billingType" : "FIXED_COST_FOR_TICKETS", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "40000000086881212", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }

List Account Time Entries

This API lists time entries recorded for a ticket or task related to an account.

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC@

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

GET /api/v1/accounts/{account_id}/timeEntry

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : "10.17",
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688128"
    },
    "secondsSpent" : "22",
    "parent" : {
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Account Time Entries

This API fetches summation of time entries for an account from your help desk

Query Params

Param Name

Data Type

Description

module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/accounts/{account_id}/timeEntrySummation

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Ticket Timer

Ticket timer is a feature that records the time an agent spends on resolving a ticket.

ATTRIBUTES

Attribute Name

Data Type

Description

hours

integer

No. of hours spent

minutes

integer

No. of minutes spent

seconds

integer

No. of seconds spent

state

integer

State of the timer. States can be RUNNING, PAUSED, INIT

Example

{ "hours" : 0, "seconds" : 26, "minutes" : 5, "state" : "RUNNING" }

Get Ticket Timer

This API fetches the time elapsed in the ticket timer, along with the current state

GET /api/v1/tickets/{ticket_id}/timer

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/tickets/13000000021183/timer
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}

Performs Ticket Timer actions

This API performs timer-related actions, such as START, STOP, PAUSE and RESUME

Query Params

Param Name

Data Type

Description

action

String

required

Action of the timer.Supported actions are START, STOP, PAUSE and RESUME

POST /api/v1/tickets/{ticket_id}/timer

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST http://desk.zoho.com/api/v1/tickets/13000000021183/timer?action=START
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 0,
  "minutes" : 0,
  "state" : "RUNNING"
}

Task Timer

Task timer is the feature that records the time an agent spends on completing a task.

ATTRIBUTES

Attribute Name

Data Type

Description

hours

integer

No. of hours spent

minutes

integer

No. of minutes spent

seconds

integer

No. of seconds spent

state

integer

State of the timer. States can be RUNNING, PAUSED, INIT

Example

{ "hours" : 0, "seconds" : 26, "minutes" : 5, "state" : "RUNNING" }

Get Task Timer

This API fetches the time elapsed in the task timer, along with the current state

GET /api/v1/tasks/{task_id}/timer

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/tasks/13000000021183/timer
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}

Performs Task Timer actions

This API performs timer-related actions, such as START, STOP, PAUSE and RESUME

Query Params

Param Name

Data Type

Description

action

String

required

Action of the timer.Supported actions are START, STOP, PAUSE and RESUME

POST /api/v1/tasks/{task_id}/timer

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST http://desk.zoho.com/api/v1/tasks/13000000075019/timer?action=START
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 0,
  "minutes" : 0,
  "state" : "RUNNING"
}

Active Timer

Active timer will fetch currently active [either running (or) paused] timer(s) details

Example

{ "timer" : { "hours" : 93, "seconds" : 9, "minutes" : 6, "state" : "Init | Running | Paused" }, "task" : { "subject" : "New Testing Task", "dueDate" : "2017-08-22 16:16:16", "depId" : "7000000016007", "id" : "7000000020001", "depName" : "AutomationCheck2", "status" : "In Progress" }, "ticket" : { "ticketNumber" : "101", "subject" : "Sample", "dueDate" : "2017-08-22 16:16:16", "depId" : "7000000016005", "id" : "7000000009092", "depName" : "AutomationCheck2", "status" : "Open" }, "entity" : "Tasks" }

Get Active Timer for an Agent

This API fetches currently running timer details for an agent

Query Params

Param Name

Data Type

Description

departmentId
see documentation

long

required

Department to which the ticket belongs

limit

Integer

optional,
range : 1-50

limit

from

Integer

optional

from

GET /api/v1/myActiveTimers

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/myActiveTimers?departmentId=7000000022910?from=0&limit=10
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "timer" : {
      "hours" : 3,
      "seconds" : 30,
      "minutes" : 6,
      "state" : "RUNNING"
    },
    "task" : {
      "subject" : "Bug Fix #120",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016001",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016005",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Tasks"
  }, {
    "call" : {
      "subject" : "Firt Call",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016002",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "timer" : {
      "hours" : 3,
      "seconds" : 37,
      "minutes" : 7,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016005",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Calls"
  }, {
    "timer" : {
      "hours" : 3,
      "seconds" : 59,
      "minutes" : 7,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016007",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "event" : {
      "subject" : "First Event",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016003",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "entity" : "Events"
  }, {
    "timer" : {
      "hours" : 3,
      "seconds" : 4,
      "minutes" : 8,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Tickets"
  } ]
}

List ticket timers

This API fetches the details of timers currently active in a ticket.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the timers must be fetched

limit

integer

optional,
range : 1-100

Number of timers to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the timers. Value supported is owner.

GET /api/v1/tickets/{ticket_id}/activeTimer

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/tickets/13000000021183/activeTimer?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Sam",
      "lastName" : "Jones",
      "photoURL" : "https://contacts.localzoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Sam Jones",
      "id" : "7000000020001"
    },
    "timer" : {
      "hours" : 93,
      "seconds" : 9,
      "minutes" : 6,
      "state" : "Running"
    },
    "userId" : "7000000020001"
  }, {
    "owner" : {
      "firstName" : "Robert",
      "lastName" : "Downey",
      "photoURL" : "https://contacts.localzoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Robert Downey",
      "id" : "7000000030001"
    },
    "timer" : {
      "hours" : 19,
      "seconds" : 24,
      "minutes" : 9,
      "state" : "Paused"
    },
    "userId" : "7000000030001"
  } ]
}

List task timers

This API fetches the details of timers currently active in a task.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the timers must be fetched

limit

integer

optional,
range : 1-100

Number of timers to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the timers. Value supported is owner.

GET /api/v1/tasks/{task_id}/activeTimer

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET http://desk.zoho.com/api/v1/tasks/13000000021183/activeTimer?include=owner
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Sam",
      "lastName" : "Jones",
      "photoURL" : "https://contacts.localzoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Sam Jones",
      "id" : "7000000020001"
    },
    "timer" : {
      "hours" : 93,
      "seconds" : 9,
      "minutes" : 6,
      "state" : "Running"
    },
    "userId" : "7000000020001"
  }, {
    "owner" : {
      "firstName" : "Robert",
      "lastName" : "Downey",
      "photoURL" : "https://contacts.localzoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Robert Downey",
      "id" : "7000000030001"
    },
    "timer" : {
      "hours" : 19,
      "seconds" : 24,
      "minutes" : 9,
      "state" : "Paused"
    },
    "userId" : "7000000030001"
  } ]
}

Ticket Tags

Ticket tags refer to the keywords added to tickets to ensure quick grouping, filtering, and reference.

Search tags

This API searches for tags added in your help desk portal.

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which the tags must be fetched

limit

int

optional,
range : 1-100

Number of tags to fetch

departmentId
see documentation

long

required

ID of the department from which the tags must be fetched.

searchVal

String

optional

Search keyword related to the tag.

GET api/v1/tags/search

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tags/search
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "sample",
    "tagType" : "SYSTEM",
    "id" : 123234324
  } ]
}

List ticket tags

This API lists the ticket tags added in your help desk portal.�

Query Params

Param Name

Data Type

Description

departmentId
see documentation

long

required

ID of the department from which the tags must be fetched

sortBy

string

optional,
max chars : 100

Key that sorts tags by a specific attribute: createdTime or count. The default sorting order is descending.

from

int

optional

Index number, starting from which the tags must be fetched

limit

int

optional,
range : 1-100

Number of tags to fetch

GET api/v1/ticketTags

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketTags
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketCount" : "10",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  }, {
    "ticketCount" : "0",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  } ]
}

List tickets by tag

This API lists tickets containing the tag specified.

Query Params

Param Name

Data Type

Description

from

int

optional

Index number, starting from which tickets must be fetched.

limit

int

optional,
range : 1-100

Number of tickets to list

assignee

string

optional,
max chars : 100

User assigned to resolve the ticket. Values allowed are Unassigned or a valid assigneeId. You can pass multiple assigneeIds as comma-separated values.

channel

string

optional,
max chars : 100

Channel through which the tickets were received. You can pass multiple values by separating them with commas.

status

string

optional,
max chars : 100

Resolution status of the tickets. You can pass multiple values by separating them with commas.

receivedInDays

integer

optional

Number of days since the tickets were received. Values allowed are 15, 30 , 90.

priority

string

optional,
max chars : 100

Priority of the tickets. You can pass multiple values by separating them with commas.

sortBy

string

optional,
max chars : 100

Key that sorts the tickets by a specific attribute: dueDate, recentThread, createdTime, or ticketNumber. The default sorting order is ascending. A - prefix denotes a descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Additional information related to the tickets. Values allowed are: contacts, products, departments, team, isRead and assignee. You can pass multiple values by separating them with commas.

GET api/v1/tags/{tag_id}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tags/1892000001010007/tickets?include=assignee,contacts,departments,team,isRead
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : true,
    "language" : "English",
    "closedTime" : null,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8838109870",
      "id" : "1892000000042032",
      "isSpam" : false,
      "type" : "paid",
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "isSpam" : false,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Facebook",
    "isRead" : true,
    "closedTime" : null,
    "contact" : {
      "lastName" : "Richard",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8838109870",
      "id" : "1892000000093203",
      "isSpam" : false,
      "type" : "paid",
      "email" : "richard@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "isSpam" : false,
    "status" : "Open"
  } ]
}

Associate Tag

This API adds a single tag or multiple tags to a ticket.

Attributes

Param Name

Data Type

Description

tags

list

required

Names of the tags

POST /api/v1/tickets/{ticket_id}/associateTag

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/associateTag
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "tags" : [ "sample", "ticket", "tag" ]
}'

Response Example

{
  "data" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "ticket",
    "tagType" : "MANUAL",
    "id" : 1232343244
  }, {
    "name" : "tag",
    "tagType" : "SYSTEM",
    "id" : 12323432434
  } ]
}

Dissociate Tag

This API removes a single tag or multiple tags from a ticket.

Attributes

Param Name

Data Type

Description

tags

list

required

Names of the tags

POST /api/v1/tickets/{ticket_id}/dissociateTag

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/dissociateTag
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "tags" : [ "sample", "ticket", "tag" ]
}'

Response Example

List tags in a ticket

This API lists tags associated with a ticket.

GET api/v1/tickets/{ticket_id}/tags

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/tags
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "tags" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  } ]
}

List recent tags

This API lists the five most recent tags associated with tickets.

Query Params

Param Name

Data Type

Description

departmentId
see documentation

long

required

ID of the department from which the tags must be fetched

GET api/v1/recentTicketTags

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/recentTicketTags
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketCount" : "10",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  }, {
    "ticketCount" : "0",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  } ]
}

Update recent tags

This API adds a tag to the list of recently viewed tags. tag_id is a mandatory parameter in the API request.

POST /api/v1/recentTicketTags/{tag_id}

OAuth Scope

Desk.tickets.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/recentTicketTags/42312412421
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

CustomerHappiness

Customer Happiness Measure

List all customerHappiness

Get customer-happiness list for a given department. You can also use any one of the sub modules: agentId, contactId, accountId, or ticketId at a time.

Query Params

Param Name

Data Type

Description

department

String

required

Mandatory param to fetch the customer-happiness list for a given ID of the department. You can also provide department as allDepartment to fetch customer happiness from all departments

agentId

Long

optional

Filter that returns the customer-happiness list for a particular agent

contactId

Long

optional

Filter that returns the customer-happiness list for a particular contact

accountId

Long

optional

Filter that returns the customer-happiness list for a particular account

ticketId

Long

optional

Filter that returns the customer-happiness list for a particular ticket

startTime

Long

optional

Start time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

endTime

Long

optional

Start time till which the customer-happiness list should show. End time should be in GMT time zone and in milliseconds

from

int

optional

The startng index from which the list should be displayed based on the time of receiving customer feedback

limit

int

optional,
range : 1-50

Number of ratings to be displayed in the list

rating

string

optional,
max chars : 100

Segregate the list based on the type of rating. Allowed values are good, ok, or bad

duration

string

optional,
max chars : 100

Period from which the customer happiness rating must be fetched. Values allowed are: TODAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_7_DAYS, YESTERDAY, LAST_1_HOUR, CUSTOM_IN_DATE, LAST_100_RATINGS, LAST_24_HOUR and LAST_30_DAYS

startDate

timestamp

optional

start date time

endDate

timestamp

optional

end date time

sortBy

string

optional,
max chars : 100

Sorted by ratedtime

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, tickets, agents. You can include both by separating them with a comma in the query param.

GET api/v1/customerHappiness

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/customerHappiness?authtoken=ae075d0de8621f986c07c1fe256e4243&orgId=1234567&department=3000000023770
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "agentId" : "5000000015959",
    "agent" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000015959/photo",
      "id" : "5000000015959",
      "email" : "jack@asdad.com"
    },
    "ticket" : {
      "ticketNumber" : "118",
      "subject" : "GPS not working",
      "id" : "5000000074060"
    },
    "contactId" : "5000000017055",
    "departmentId" : "5000000056329",
    "rating" : "GOOD",
    "threadId" : "5000000090001",
    "feedback" : "Great Work!!!",
    "accountId" : "5000000017043",
    "ratedTime" : "2018-09-25T11:08:58.235Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Nirmal Kumar",
      "id" : "5000000017055"
    },
    "id" : "5000000090012",
    "ticketId" : "5000000074060"
  }, {
    "agentId" : "5000000015959",
    "agent" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000015959/photo",
      "id" : "5000000015959",
      "email" : "jack@asdad.com"
    },
    "ticket" : {
      "ticketNumber" : "117",
      "subject" : "Apps take time to load",
      "id" : "5000000056151"
    },
    "contactId" : "5000000026602",
    "departmentId" : "5000000042101",
    "rating" : "BAD",
    "threadId" : "5000000092045",
    "feedback" : "The solution provided doesn't seem to work.",
    "accountId" : "-1",
    "ratedTime" : "2018-09-26T10:47:35.936Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Phillip Collins",
      "id" : "5000000026602"
    },
    "id" : "5000000092056",
    "ticketId" : "5000000056151"
  }, {
    "agentId" : "5000000015959",
    "ticket" : {
      "ticketNumber" : "114",
      "subject" : "zPhone battery needs to be fixed",
      "id" : "5000000055051"
    },
    "contactId" : "5000000017055",
    "departmentId" : "5000000012860",
    "rating" : "OKAY",
    "threadId" : "5000000092069",
    "feedback" : "The battery performance is better but I expect a little more.",
    "accountId" : "5000000017043",
    "ratedTime" : "2018-09-26T10:49:16.202Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Sam Rossner",
      "id" : "5000000017055"
    },
    "id" : "5000000092084",
    "ticketId" : "5000000055051"
  } ]
}

Get customer happiness count

This API gives you the count of the ratings given by the customers for each category of a given department. You can also use any one of the sub modules: agentId, contactId, accountId, or ticketId at a time.

Query Params

Param Name

Data Type

Description

department

String

required

Mandatory param to fetch the customer-happiness list for a given ID of a department. You can also provide department as allDepartment to fetch customer-happiness list from all the departments

agentId

Long

optional

Filter that returns the customer-ratings count for a particular agent

contactId

Long

optional

Filter that returns the customer-ratings count for a particular contact

accountId

Long

optional

Filter that returns the customer-ratings count for a particular account

ticketId

Long

optional

Filter that returns the customer-ratings count for a particular ticket

startTime

Long

optional

Start time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

endTime

Long

optional

Start time till which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

duration

string

optional,
max chars : 100

startDate

timestamp

optional

start date time

endDate

timestamp

optional

end date time

from

Integer

optional

The from index

limit

Integer

optional,
range : 1-50

Number of rating to be displayed

GET api/v1/customerHappiness/count

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/customerHappiness/count?authtoken=ae075d0de8621f986c07c1fe256e4243&orgId=1234567&department=30000002344
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "30000002344" : {
    "bad" : 3,
    "ok" : 2,
    "good" : 5
  }
}

Ticket Templates

Ticket templates are provisions that automatically populate predefined values in ticket fields, thereby helping users save time and effort while adding new tickets.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the ticket template

ticketTemplateName

string

Name of the ticket template

showInCustomerPortal

boolean

Key that specifies if the template must be displayed in the help center or not

layoutId

long

ID of the ticket layout from which the template is derived

ticketTemplateValues

show Attributes

list

Values to auto-populate in the different fields in the template

Example

{ "showInCustomerPortal" : true, "ticketTemplateName" : "temp1", "id" : "4000000020001", "layoutId" : "4000000020012", "ticketTemplateValues" : { "subCategory" : null, "cf" : { "cf_severity_percentage" : "0.0" }, "productId" : null, "contactId" : null, "subject" : null, "departmentId" : "4000000007073", "dueDate" : null, "channel" : null, "description" : null, "secondaryContacts" : [ "4000000009076", "4000000009062" ], "priority" : null, "classification" : null, "assigneeId" : null, "accountId" : null, "phone" : "9876545645", "category" : null, "email" : "jacks@zylker.com", "status" : null } }

Create ticket template

This API helps create a ticket template in your help desk portal.

Attributes

Param Name

Data Type

Description

ticketTemplateName

string

required,
max chars : 200

Name of the ticket template

showInCustomerPortal

boolean

optional

Key that specifies if the template must be displayed in the help center or not

ticketTemplateValues

list

required

Values to auto-populate in the different fields in the template

POST api/v1/ticketTemplates

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/ticketTemplates
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "showInCustomerPortal" : true, "ticketTemplateName" : "temp1", "ticketTemplateValues" : { "cf" : { "cf_severity_percentage" : "0.0" }, "phone" : "9876545645", "departmentId" : "4000000007073", "email" : "jacks@zylker.com" }, "layoutId" : "4000000020012" }'

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : null,
    "contactId" : null,
    "subject" : null,
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "category" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

Get ticket template

This API fetches the details of a particular ticket template.

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the template. Values allowed are: contacts, products, departments, team, and assignee. You can pass multiple values by separating them using commas in the API request.

GET api/v1/ticketTemplates/{ticketTemplates_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketTemplates/4000000020001?include=departments,assignee,contacts,team,products
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "product" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : null,
    "contactId" : null,
    "subject" : null,
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "contact" : null,
    "assignee" : null,
    "department" : {
      "name" : "testing department",
      "id" : "4000000007073"
    },
    "category" : null,
    "account" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

List ticket templates

This API lists a particular number of ticket templates, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the templates must be fetched

departmentId
see documentation

long

optional

ID of the department from which templates must be fetched

layoutId

long

optional

ID of the layout from which templated must be fetched for the given department ID

limit

integer

required,
default : 10,
range : 1-100

Number of templates to list. The default value is 10 and the maximum value supported is 100

showInCustomerPortal

boolean

optional

Visibility of the templates in the help center

~~templateName~~

deprecated

String

optional

Name of the template

searchStr

String

optional

String to search for ticket templates by ticket template name

GET api/v1/ticketTemplates

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketTemplates
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "showInCustomerPortal" : true,
    "ticketTemplateName" : "Template1",
    "id" : "4000000020001",
    "layoutId" : "4000000020121"
  }, {
    "showInCustomerPortal" : false,
    "ticketTemplateName" : "Template2",
    "id" : "4000000020063",
    "layoutId" : "4000000020431"
  } ]
}

Update ticket template

This API helps update the details of a particular ticket template.

Attributes

Param Name

Data Type

Description

ticketTemplateName

string

optional,
max chars : 200

Name of the ticket template

showInCustomerPortal

boolean

optional

Key that specifies if the template must be displayed in the help center or not

ticketTemplateValues

list

optional

Values to auto-populate in the different fields in the template

PATCH api/v1/ticketTemplates/{ticketTemplates_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/ticketTemplates/4000000020001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "showInCustomerPortal" : false, "ticketTemplateName" : "temptest", "ticketTemplateValues" : { "cf" : { "cf_severity_percentage" : "60" }, "productId" : "4000000009012", "subject" : "UrgentProblem", "departmentId" : "4000000007073", "email" : "jacks@zylker.com" } }'

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temptest",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : "4000000009012",
    "contactId" : null,
    "subject" : "UrgentProblem",
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "category" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

Delete ticket template

This API deletes a ticket template from your help desk portal.

Attributes

Param Name

Data Type

Description

ids

list

required

Array of Entity id to be deleted

POST api/v1/ticketTemplates/deleteMany

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/ticketTemplates/deleteMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "4000000083313", "4000000082105" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "2000000021011",
    "errors" : null
  }, {
    "success" : false,
    "id" : "4000000082105",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Tickets Comments

Ticket comments are ticket-related conversations that occur mainly between different agents in your help desk portal. Comments marked as private in a ticket are visible only to agents, whereas comments marked as public appear on the customer portal too.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

isPublic

boolean

Key that returns if a comment is public or not. The value of this key can be set only at the time of making a comment.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of creating the comment

modifiedTime

timestamp

Time of modifying the comment

commenter

show Attributes

object

Details of the user who made the comment.

attachmentIds
see documentation

list

List of file attachments in the comment. For more information on attachments, refer to the Uploads section of this document.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "pandeeswaran.s+stp@zohocorp.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create ticket comment

This API adds a comment to a ticket. To include an @mention, follow this format: zsu[@user:{zuid}]zsu.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

isPublic

boolean

optional

Key that returns if a comment is public or not. The value of this key can be set only at the time of making a comment.

attachmentIds
see documentation

list

optional

List of file attachments in the comment. For more information on attachments, refer to the Uploads section of this document.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/tickets/{ticket_id}/comments

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isPublic" : "true",
  "attachmentIds" : [ "4000000008892" ],
  "contentType" : "html",
  "content" : "zsu[@user:11550965]zsu Please fix this ASAP"
}'

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment commentObj = new Comment();
commentObj.setContentType(contentType);
commentObj.setContent(content);
Comment response = comment.createTicketComment( ticketId, commentObj );

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008892",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008892/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.193Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "contentType" : "html",
  "content" : "zsu[@user:11550965]zsu Please fix this ASAP",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update ticket comment

This API modifies an existing comment. To include an @mention, follow this format: zsu[@user:{zuid}]zsu.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

isPublic

boolean

optional

Key that returns if a comment is public or not. The value of this key can be set only at the time of making a comment.

attachmentIds
see documentation

list

optional

List of file attachments in the comment. For more information on attachments, refer to the Uploads section of this document.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "4000000008994" ],
  "content" : "Edited comment."
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.163Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Fixed the issue.",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete ticket comment

This API deletes a comment.

DELETE api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
boolean response = comment.deleteTicketComment( commentId, ticketId );

Response Example

Get ticket comment

This API fetches a ticket comment from your help desk portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getTicketComment( commentId, ticketId, include );

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.000Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "pandeeswaran.s+stp@zohocorp.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all ticket comments

This API lists a particular number of comments recorded on a ticket, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

Number of comments to fetch

sortBy

string

optional,
max chars : 100

Sort by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tickets/{ticket_id}/comments

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getTicketComments( ticketId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-01-24T14:12:45.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_edited.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:06:58.000Z",
    "isPublic" : true,
    "id" : "4000000529001",
    "contentType" : "html",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "commenterId" : "4000000008692",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "pandeeswaran.s+stp@zohocorp.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T14:14:37.000Z",
    "isPublic" : false,
    "id" : "4000000529007",
    "contentType" : "html",
    "content" : "zsu[@user:55616589]zsu Please fix this ASAP",
    "commenterId" : "4000000008692",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "0",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "pandeeswaran.s+stp@zohocorp.com",
      "zuid" : "55616589"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Get a ticket comment history

This API fetches the history of comments recorded on a ticket, including instances of adding and editing the comments.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the comment activities must be fetched

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

limit

integer

required,
default : 50,
range : 1-100

Number of comment activities to fetch

GET api/v1/tickets/{ticket_id}/comments/{comment_id}/history

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/history
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getTicketCommentHistory( commentId, ticketId, from, limit, include );

Response Example

{
  "data" : [ {
    "attachments" : [ "sample.png", "sam.txt" ],
    "commentedTime" : "2013-11-04T11:21:07.912Z",
    "isPublic" : false,
    "commenterId" : 13231241244,
    "content" : "hello comment",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "CEO",
      "type" : "AGENT",
      "email" : "hagdsag@hfhjd.com"
    }
  }, {
    "attachments" : [ "sample.png", "sam.txt" ],
    "commentedTime" : "2013-11-04T11:21:07.912Z",
    "isPublic" : true,
    "commenterId" : 13231241244,
    "content" : "hello comment",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "hagdsag@hfhjd.com"
    }
  } ]
}

Contacts Comments

Contact comments refer to comments recorded on contacts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a contact comment

This API adds a comment to a contact.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/contacts/{contact_id}/comments

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000530041/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First contact comment"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:34:56.358Z",
  "id" : "4000000530043",
  "contentType" : "html",
  "content" : "First contact comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a contact comment

This API updates an existing contact comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530045
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "second contact comment edit"
}'

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment commentObj = new Comment();
commentObj.setContent(content);
Comment response = comment.updateContactComment( contactId, commentId, commentObj );

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:35:23.000Z",
  "id" : "4000000530045",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second contact comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a contact comment

This API deletes an existing contact comment.

DELETE api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530037
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
boolean response = comment.deleteContactComment( contactId, commentId );

Response Example

Get a contact comment

This API fetches a contact comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530043?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getContactComment( contactId, commentId, include );

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:34:56.000Z",
  "id" : "4000000530043",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all contact comments

This API lists a particular number of comments recorded on a contact, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contacts/{contact_id}/comments

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000530041/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getContactComments( contactId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:35:23.000Z",
    "id" : "4000000530045",
    "contentType" : "plainText",
    "content" : "second contact comment",
    "commenterId" : "4000000008692",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:34:56.000Z",
    "id" : "4000000530043",
    "contentType" : "html",
    "content" : "First contact comment",
    "commenterId" : "4000000008692",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "CEO",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Accounts Comments

Account comments refer to comments made on accounts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create an account comment

This API adds a comment to an account.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/accounts/{account_id}/comments

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First account comment"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:45:21.167Z",
  "id" : "4000000530047",
  "contentType" : "html",
  "content" : "First account comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update an account comment

This API updates an existing account comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "second account comment edit"
}'

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment commentObj = new Comment();
commentObj.setContent(content);
Comment response = comment.updateAccountComment( accountId, commentId, commentObj );

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:45:21.000Z",
  "id" : "4000000530047",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second account comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete an account comment

This API deletes an existing account comment.

DELETE api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
boolean response = comment.deleteAccountComment( accountId, commentId );

Response Example

Get an account comment

This API fetches an account comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getAccountComment( accountId, commentId, include );

Response Example

{
  "modifiedTime" : "2017-01-24T19:46:24.000Z",
  "commentedTime" : "2017-01-24T19:45:21.000Z",
  "id" : "4000000530047",
  "contentType" : "plainText",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "4000000008692",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all account comments

This API lists a particular number of comments recorded on an account, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched.

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/accounts/{account_id}/comments

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getAccountComments( accountId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:45:55.000Z",
    "id" : "4000000530049",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    }, {
      "offSet" : "59",
      "departmentId" : "3113800000634345",
      "length" : "26",
      "id" : "3113800000143134",
      "type" : "TICKET"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T19:46:24.000Z",
    "commentedTime" : "2017-01-24T19:45:21.000Z",
    "id" : "4000000530047",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    }, {
      "offSet" : "59",
      "departmentId" : "3113800000634345",
      "entityNumber" : "1342",
      "length" : "26",
      "name" : "",
      "id" : "3113800000143134",
      "type" : "TICKET"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Tasks Comments

Task comments refer to comments recorded on tasks assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a task comment

This API adds a comment to a task.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/tasks/{task_id}/comments

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks/4000000530001/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First Task comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Task comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a task comment

This API updates an existing task comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "Edit Task comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Task comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a task comment

This API deletes an existing task comment.

DELETE api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get a task comment

This API fetches a task comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530005?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Task Comment......",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all task comments

This API lists a particular number of comments recorded on a task, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tasks/{task_id}/comments

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000530001/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Second Task Comment......",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Task comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Articles Comments

Article comments refer to comments recorded on help articles in the knowledge base. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a translation comment

This API adds a comment to an article translation.

Attributes

Param Name

Data Type

Description

content

string

required,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

isPublic

boolean

required

Visibility of the comment, which can be set only at the time of commenting.

contentType

string

required,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/articles/{article_id}/translations/{locale}/comments

OAuth Scope

Desk.articles.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First article comment"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:28:35.309Z",
  "isPublic" : false,
  "id" : "4000000530037",
  "contentType" : "html",
  "content" : "First article comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a translation comment

This API updates an existing article translation comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

isPublic

boolean

optional

Visibility of the comment, which can be set only at the time of commenting.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4000000530037
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "first article comment edit"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:28:35.000Z",
  "isPublic" : false,
  "id" : "4000000530037",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "first article comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a translation comment

This API deletes an existing article translation comment.

DELETE api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4000000530037
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.deleteArticleComment( articleId, commentId, locale );

Response Example

Get a article translation comment

This API fetches an article translation comment from the portal.

GET api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4000000530037
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getArticleComment( articleId, commentId, locale );

Response Example

{
  "modifiedTime" : "2017-01-24T19:29:59.000Z",
  "commentedTime" : "2017-01-24T19:28:35.000Z",
  "isPublic" : false,
  "id" : "4000000530037",
  "contentType" : "plainText",
  "content" : "first article comment edit",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all translation comments

This API lists a particular number of comments recorded on an article translation, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

required,
default : 1,
range : >0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 5,
range : 1-10

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET api/v1/articles/{article_id}/translations/{locale}comments

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getArticleComments( articleId, locale, from, limit, sortBy, isAscending );

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:29:22.000Z",
    "isPublic" : false,
    "id" : "4000000530039",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "second article comment",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T19:29:59.000Z",
    "commentedTime" : "2017-01-24T19:28:35.000Z",
    "isPublic" : false,
    "id" : "4000000530037",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "first article comment edit",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Contracts Comments

Contract comments refer to comments recorded on SLA contracts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a contract comment

This API adds a comment to a contract.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/contracts/{contract_id}/comments

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contracts/4000000230035/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First contract comment"
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008892",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008892/content"
  } ],
  "commentedTime" : "2017-01-24T19:49:34.472Z",
  "id" : "4000000530051",
  "contentType" : "html",
  "content" : "First contract comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a contract comment

This API updates an existing contract comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "second contract comment edit"
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T19:50:08.000Z",
  "id" : "4000000530053",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second contract comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a contract comment

This API deletes an existing contract comment.

DELETE api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get a contract comment

This API fetches a contract comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-01-24T19:50:40.000Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T19:50:08.000Z",
  "id" : "4000000530053",
  "contentType" : "plainText",
  "content" : "second contract comment edit",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

List all contract comment

This API lists a particular number of comments recorded on a contract, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contracts/{contract_id}/comments

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contracts/4000000230035/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-01-24T19:50:40.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_edited.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T19:50:08.000Z",
    "id" : "4000000530053",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "second contract comment edit",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:49:34.000Z",
    "id" : "4000000530051",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "First contract comment",
    "mention" : [ ]
  } ]
}

Uploads

Uploads are temporary file attachments that exist with a ticket for a period of 24 hours.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "size" : "4769", "creatorId" : "4000000008692", "name" : "zoho.jpeg", "createdTime" : "2016-06-23T07:31:42.000Z", "isPublic" : false, "id" : "4000000055001" }

Upload file

This API uploads a file.

Query Params

Param Name

Data Type

Description

File Params

file

Content-Type:multipart/form-data

File to attach

POST /api/v1/uploads

OAuth Scope

Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/uploads
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

UploadAPI upload = ZDesk.getUploadAPIInstance(mailId);
Upload response = upload.uploadFile( file );

Response Example

{
  "size" : "4769",
  "creatorId" : "4000000008692",
  "name" : "zoho.jpeg",
  "createdTime" : "2016-06-23T07:31:42.000Z",
  "isPublic" : false,
  "id" : "4000000055001",
  "href" : "https://desk.zoho.com/api/v1/uploads/1892000001008043/contents"
}

Ticket Attachments

Ticket attachments are files you attach to a ticket to aid quick resolution.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "creator" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902", "id" : "1892000000047001", "email" : "jade@zylker.zohodesk.com" }, "size" : "1079", "creatorId" : "1892000000047001", "name" : "ScreenShot", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : true, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content" }

List ticket attachments

This API lists the files attached to a ticket.

Query Params

Param Name

Data Type

Description

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

isPublic

Boolean

optional

Key that returns if the attachment is public or no

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/tickets/{ticket_id}/attachments

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments?include=creator
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
GetTicketAttachmentsFilter filter = new GetTicketAttachmentsFilter.Builder().setIsPublic(isPublic).build();
List<Attachment> response = attachment.getTicketAttachments( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "issues.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : true,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "guidelines.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : true,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "CreditHistory.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "values.txt",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Ticket attachment

This API attaches a file to a ticket.

Query Params

Param Name

Data Type

Description

isPublic

Boolean

optional

Field that determines whether the attachment is public or private

File Params

file

Content-Type:multipart/form-data

File to attach to the ticket

POST /api/v1/tickets/{ticket_id}/attachments

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.createTicketAttachment( file, ticketId, filter );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042001",
  "name" : "issues.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001/content"
}

Update Ticket attachment

This API updates an existing attachment.

Attributes

Param Name

Data Type

Description

isPublic

boolean

optional

Whether to Show

PATCH /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk .zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isPublic" : true
}'

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.updateTicketAttachment( attachmentId, ticketId, attachmentObj );

Response Example

Delete Ticket attachment

This API deletes an attachment from a ticket.

DELETE /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
boolean response = attachment.deleteTicketAttachment( attachmentId, ticketId );

Response Example

Contacts Attachments

Contact attachments are files you attach to a contact to provide more context and reference information to other users.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "creator" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902", "id" : "1892000000047001", "email" : "jade@zylker.zohodesk.com" }, "size" : "2345", "creatorId" : "1892000000047001", "name" : "contact_details.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content" }

List Contact Attachments

This API lists the files attached to a contact.

Query Params

Param Name

Data Type

Description

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/contacts/{contact_id}/attachments

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments?include=creator
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
List<Attachment> response = attachment.getContactAttachments( contactId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "creation.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "profile.jpg",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "contact_MobileNo.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "contact_profile.jpg",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Contact Attachment

This API attaches a file to a contact.

File Params

file

Content-Type:multipart/form-data

File to attach to the contact

POST /api/v1/contacts/{contact_id}/attachments

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.createContactAttachment( file, contactId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "profile.jpg",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001/content"
}

Delete Contact attachment

This API removes an attachment from a contact.

DELETE /api/v1/contacts/{contact_id}/attachments/{attachment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
boolean response = attachment.deleteContactAttachment( contactId, attachmentId );

Response Example

Accounts Attachments

Account attachments are files you attach to an account to provide more context and reference information to other users.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "creator" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902", "id" : "1892000000047001", "email" : "jade@zylker.zohodesk.com" }, "size" : "2345", "creatorId" : "1892000000047001", "name" : "Associated_contacts.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content" }

List Account attachments

This API lists the files attached to an account.

Query Params

Param Name

Data Type

Description

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/accounts/{account_id}/attachments

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments?include=creator
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
List<Attachment> response = attachment.getAccountAttachments( accountId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "profile_photo.jpg",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "profile.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "logo.jpg",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "profile.pdf",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Account attachment

This API attaches a file to an account.

File Params

file

Content-Type:multipart/form-data

File to attach to the account

POST /api/v1/accounts/{account_id}/attachments

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.createAccountAttachment( file, accountId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "AccountDetails.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001/content"
}

Delete Account attachment

This API deletes an attachment from a account.

DELETE /api/v1/accounts/{account_id}/attachments/{attachment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
boolean response = attachment.deleteAccountAttachment( accountId, attachmentId );

Response Example

Contact Deduplication

Deduplication refers to identifying multiple resources containing the same information and consolidating them into a single, unique resource. The process of deduplicating multiple entries of the same contact is called contact deduplication.

Example

[ { "fieldValue" : "Jade", "contacts" : [ { "lastName" : "Jade", "secondaryEmail" : null, "ownerId" : null, "type" : null, "accountId" : "1892000000091433", "firstName" : "Jonathan", "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo", "phone" : "555555", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "createdTime" : "2017-10-12T13:11:50.000Z", "zohoCRMContact" : null, "id" : "1892000000772003", "customerHappiness" : { "badPercentage" : "0", "okPercentage" : "0", "goodPercentage" : "0" }, "email" : "case@zylker.com" }, { "lastName" : "Jade", "secondaryEmail" : null, "ownerId" : null, "type" : null, "accountId" : "1892000000052077", "firstName" : "Christ", "photoURL" : null, "phone" : null, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "createdTime" : "2017-10-12T13:11:50.000Z", "zohoCRMContact" : { "id" : "1892000000772030", "type" : "contacts_leads" }, "id" : "1892000000772001", "isSpam" : false, "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "email" : "jade@zylker.com" } ] } ]

List duplicate contacts

This API lists the duplicate entries of a contact.The fieldName parameters is mandatory in the API request

Note:
If you encounter a 202 status code while executing this API request, it means there are 100,000 or more contacts in the help desk portal. Matching the records and finding duplicates will be time-consuming in such a scenario. Therefore, the deduplication request will be accepted, and after the process is completed, an automated report will be sent to the user who initiated the deduplication.

Query Params

Param Name

Data Type

Description

fieldName

string

optional,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
firstName,

lastName,

email,

secondaryEmail,

phone,

fullName,
and
bothEmail.

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the contacts must be fetched

limit

integer

optional,
range : 1-100

Number of contacts to fetch

sortBy

string

optional,
max chars : 100

Key that sorts the contacts by a specific attribute: count or fieldValue. The default sorting order is ascending. A - prefix denotes descending order of sorting

swFieldValue

string

optional,
max chars : 100

Key that specifies the letter with which the field values must start

GET /api/v1/groupContactDuplicateValues

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groupContactDuplicateValues
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "count" : 16,
    "fieldValue" : "Jade"
  }, {
    "count" : 2,
    "fieldValue" : "saran"
  } ]
}

List details of duplicate contacts

This API lists all the details of duplicate contacts.The fieldName and fieldValues parameters are mandatory in the API request

Query Params

Param Name

Data Type

Description

fieldName

string

required,
max chars : 100

Name of the field whose values must be matched for deduplication. Values allowed are:
firstName,

lastName,

email,

secondaryEmail,

phone,

fullName,
and
bothEmail.

sortBy

string

optional,
max chars : 100

Key that sorts the contacts by a specific attribute:
firstName,

lastName,

fullName,

phone,

email,

account,

createdTime,

modifiedTime

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the contacts must be fetched

limit

integer

optional,
range : 1-100

Number of contacts to fetch

fieldValues

string

required,
max chars : 100

Actual values in each field related to the contact

include
see documentation

list

optional

Secondary information related to the contact. Value allowed is: accounts

GET /api/v1/groupContacts

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groupContacts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldValue" : "Jade",
    "contacts" : [ {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000091433",
      "firstName" : "Jonathan",
      "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
      "phone" : "555555",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : null,
      "id" : "1892000000772003",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "0",
        "okPercentage" : "0",
        "goodPercentage" : "0"
      },
      "email" : "case@zylker.com"
    }, {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000052077",
      "firstName" : "Christ",
      "photoURL" : null,
      "phone" : null,
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : {
        "id" : "1892000000772030",
        "type" : "contacts_leads"
      },
      "id" : "1892000000772001",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "22",
        "okPercentage" : "31",
        "goodPercentage" : "47"
      },
      "email" : "jade@zylker.com"
    } ]
  }, {
    "fieldValue" : "Christ",
    "contacts" : [ {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000091433",
      "firstName" : "Christ",
      "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
      "phone" : "555555",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : null,
      "id" : "1892000000772003",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "0",
        "okPercentage" : "0",
        "goodPercentage" : "0"
      },
      "email" : "case@zylker.com"
    }, {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000052077",
      "firstName" : "Christ",
      "photoURL" : null,
      "phone" : null,
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : {
        "id" : "1892000000772030",
        "type" : "contacts_leads"
      },
      "id" : "1892000000772001",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "22",
        "okPercentage" : "31",
        "goodPercentage" : "47"
      },
      "email" : "jade@zylker.com"
    } ]
  } ]
}

Get name of default field

This API fetches the name of the field set as the default field for contact deduplication.

GET /api/v1/contactsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contactsDeduplication/defaultFieldName
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldName" : "email"
}

Set default field for contact deduplication

This API sets the field you specify as the default field for deduplicating contacts.

Attributes

Param Name

Data Type

Description

fieldName

string

required,
max chars : 100

The name of the field

markDefault

boolean

required

to mark the given field as default or remove the field from the default.

POST /api/v1/contactsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contactsDeduplication/defaultFieldName
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldName" : "email",
  "markDefault" : true
}'

Response Example

Account Deduplication

The process of deduplicating multiple entries of the same account is called account deduplication

Example

{ "accounts" : [ { "website" : "112121", "accountName" : "Admin Account", "phone" : "121212", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "createdTime" : "2015-02-16T16:57:44.000Z", "id" : "1892000000052077", "email" : "admin@zylker.com" }, { "website" : "112121", "accountName" : "Admin Account", "phone" : "121212", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "createdTime" : "2015-02-16T16:57:44.000Z", "id" : "1892000000052077", "email" : "admin@zoho.com" } ], "fieldValue" : "Admin Account" }

List duplicate accounts

This API lists the duplicate entries of an account.The fieldName parameters is mandatory in the API request

Note:
If you encounter a 202 status code while executing this API request, it means there are 100,000 or more accounts in the help desk portal. Matching the records and finding duplicates will be time-consuming in such a scenario. Therefore, the deduplication request will be accepted, and after the process is completed, an automated report will be sent to the user who initiated the deduplication.

Query Params

Param Name

Data Type

Description

fieldName

string

optional,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
email,

phone,
and
accountName

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

swFieldValue

string

optional,
max chars : 100

Key that specifies the letter with which the field values must start

sortBy

string

optional,
max chars : 100

Key that sorts the accounts by a specific attribute: count or fieldValue. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/groupAccountDuplicateValues

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groupAccountDuplicateValues
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "count" : 16,
    "fieldValue" : "Admin Account"
  }, {
    "count" : 2,
    "fieldValue" : "Agent Account"
  } ]
}

List details of duplicate accounts

This API lists all the details of duplicate accounts.The fieldName and fieldValues parameters are mandatory in the API request

Query Params

Param Name

Data Type

Description

fieldName

string

required,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
email,

phone,
and
accountName

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

fieldValues

string

required,
max chars : 100

Actual values in each field related to the account

sortBy

string

optional,
max chars : 100

Key that sorts the accounts by a specific attribute: accountName or createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/groupAccounts

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/groupAccounts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "accounts" : [ {
      "website" : "112121",
      "accountName" : "Admin Account",
      "phone" : "121212",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2015-02-16T16:57:44.000Z",
      "zohoCRMAccount" : null,
      "id" : "1892000000052077",
      "email" : "admin@zylker.com"
    }, {
      "website" : "112121",
      "accountName" : "Admin Account",
      "phone" : "121212",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2015-02-16T16:57:44.000Z",
      "zohoCRMAccount" : null,
      "id" : "1892000000052077",
      "email" : "admin@zoho.com"
    } ],
    "fieldValue" : "Admin Account"
  }, {
    "accounts" : [ {
      "website" : "112121",
      "accountName" : "Agent Account",
      "phone" : "121212",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2015-02-16T16:57:44.000Z",
      "zohoCRMAccount" : {
        "id" : "32754000000537001"
      },
      "id" : "1892000000052077",
      "email" : "agent@zylker.com"
    }, {
      "website" : "112121",
      "accountName" : "Agent Account",
      "phone" : "121212",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2015-02-16T16:57:44.000Z",
      "zohoCRMAccount" : {
        "id" : "32754000000537001"
      },
      "id" : "1892000000052077",
      "email" : "agent@zoho.com"
    } ],
    "fieldValue" : "Agent Account"
  } ]
}

Get Default Field Name

This API fetches the name of the field set as the default field for account deduplication.

GET /api/v1/accountsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accountsDeduplication/defaultFieldName
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldName" : "email"
}

Set default field for account deduplication

This API sets the field you specify as the default field for deduplicating accounts.

Attributes

Param Name

Data Type

Description

fieldName

string

required,
max chars : 100

The name of the field

markDefault

boolean

required

to mark the given field as default or remove the field from the default.

POST /api/v1/accountsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accountsDeduplication/defaultFieldName
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldName" : "accountName",
  "markDefault" : true
}'

Response Example

Account Followers

Account followers are users who follow an account to track the tickets raised from the account and the support provided.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

Example

{ "firstName" : "", "lastName" : "deskagent", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo", "id" : "5000000012902", "email" : "deskagent@zoho.com" }

Add account followers

This API adds one or more users to the followers list of an account

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/accounts/{account_id}/addFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/addFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Remove account followers

This API removes one or more users from the followers list of an account

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/accounts/{account_id}/removeFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/removeFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Get account followers

This API fetches the list of users following an account.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the followers must be fetched

limit

integer

optional,
range : 1-100

Number of followers to list

GET api/v1/accounts/{account_id}/followers

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/followers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "id" : "5000000012903",
    "email" : "agent@zoho.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : "deskagent@zoho.com"
  } ]
}

Contact Followers

Contact followers are users who follow a contact to track the tickets raised by the contact and the support provided.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

Example

{ "firstName" : "", "lastName" : "deskagent", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo", "id" : "5000000012902", "email" : "deskagent@zoho.com" }

Add contact followers

This API adds one or more users to the followers list of a contact.

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/contacts/{contact_id}/addFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000190069/addFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Remove contact followers

This API removes one or more users from the followers list of a contact.

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/contacts/{contact_id}/removeFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000190069/removeFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Get contact followers

This API fetches the list of users following a contact.

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the followers must be fetched

limit

integer

optional,
range : 1-100

Number of followers to list

GET api/v1/contacts/{contact_id}/followers

OAuth Scope

Desk.contacts.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000190069/followers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "id" : "5000000012903",
    "email" : "agent@zoho.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : "deskagent@zoho.com"
  } ]
}

Ticket Followers

Ticket followers are users who follow a ticket to track the progress made in resolving it.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

following

string

Key that returns the module being followed. Values allowed are
tickets,

contacts,
or
accounts

Example

{ "firstName" : "", "lastName" : "deskagent", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo", "following" : "ticket", "id" : "5000000012902", "email" : "deskagent@zoho.com" }

Add ticket followers

This API adds one or more users to the followers list of a ticket.

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/tickets/{ticket_id}/addFollowers

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000190069/addFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Remove ticket followers

This API removes one or more users from the followers list of a ticket.

Attributes

Param Name

Data Type

Description

followerIds

list

required

the list of ids to be added as follower

POST api/v1/tickets/{ticket_id}/removeFollowers

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000190069/removeFollowers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

Get ticket followers

This API fetches the list of users following a ticket.

Note:
Sometimes, followers of a contact/account indirectly end up as ticket followers if the ticket is associated with the contact/account they follow. In that case, the following key returns the value of the original module the user follows--*contact* or account.

Even in a case where the user first followed the ticket and then followed the contact/account associated with it, the following key returns the value contact or account. This is because the contact/account is the parent resource of the ticket.

GET api/v1/tickets/{ticket_id}/followers

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/followers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "following" : "ticket",
    "id" : "5000000012903",
    "email" : "agent@zoho.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "following" : "contact",
    "id" : "5000000012902",
    "email" : "deskagent@zoho.com"
  } ]
}

Tasks Attachments

Task attachments are files you attach to a task to aid quick resolution.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "creator" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902", "id" : "1892000000047001", "email" : "jade@zylker.zohodesk.com" }, "size" : "2345", "creatorId" : "1892000000047001", "name" : "taskfile.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" }

List Task attachments

This API lists the files attached to a task.

Query Params

Param Name

Data Type

Description

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/tasks/{task_id}/attachments

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments?include=creator
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
List<Attachment> response = attachment.getTaskAttachments( taskId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "issue.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "program.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "errorfixed.txt",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "error_page.pdf",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  } ]
}

Create Task attachment

This API attaches a file to a task.

File Params

file

Content-Type:multipart/form-data

File to attach to the task

POST /api/v1/tasks/{task_id}/attachments

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.createTaskAttachment( file, taskId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "task_history.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001/content"
}

Delete Task attachment

This API removes an attachment from a task.

DELETE /api/v1/tasks/{task_id}/attachments/{attachment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
boolean response = attachment.deleteTaskAttachment( attachmentId, taskId );

Response Example

Product Attachments

Product attachments are the files you attach to a product to aid quick resolution.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the attachment

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{ "creator" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902", "id" : "1892000000047001", "email" : "jade@zylker.zohodesk.com" }, "size" : "2345", "creatorId" : "1892000000047001", "name" : "product.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000047042/content" }

List all attachments

This API lists all attachments in a product.

Query Params

Param Name

Data Type

Description

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

from Index

limit

integer

optional,
range : 1-100

the number of attachments to be displayed

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/products/{product_id}/attachments

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/1892000001004024/attachments?include=creator
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
List<Attachment> response = attachment.getProductAttachments( productId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "ticket.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "bsnl-feb14.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000089041/content"
  }, {
    "size" : "97951",
    "creatorId" : "1892000000042002",
    "name" : "history.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.zohodesk.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "fixes.txt",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create an attachment

This API attaches a file to a product.

File Params

file

Content-Type:multipart/form-data

attachment to be added

POST /api/v1/products/{product_id}/attachments

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/products/1892000001004024/attachments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
Attachment response = attachment.createProductAttachment( file, productId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "tools.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001010001/content"
}

Delete an attachment

This API deletes an attachment from a product.

DELETE /api/v1/products/{product_id}/attachments/{attachment_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001010001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId);
boolean response = attachment.deleteProductAttachment( productId, attachmentId );

Response Example

Activities

Activity refers to secondary activities that your customer support agents perform. In Zoho Desk, activities are of three types: tasks, calls, and events. It is not mandatory for activities to be related only to ticket resolution.

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "reminder" : [ { "alertType" : [ "EMAIL" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T10:32:11.000Z" }, { "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T16:32:11.000Z" }, { "relativeReminderInMin" : "10", "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "RELATIVE" } ], "contactId" : "3000000008749", "customFields" : { }, "subject" : "New Event", "completedTime" : "2016-07-26T17:32:11.000Z", "departmentId" : "3000000007043", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "duration" : "30", "createdTime" : "2016-07-26T16:32:11.000Z", "modifiedBy" : { "firstName" : "George", "lastName" : "McKinson", "photoURL" : null, "id" : "5000000015911" }, "startTime" : "2016-07-26T17:02:11.000Z", "id" : "3000000018001", "isSpam" : false, "category" : "Meeting", "ticketId" : "3000000008753", "status" : "completed" }

List ticket activities

This API lists a particular number of activities associated with a ticket, based on the limit specified.

Mock API

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the activities must be listed

isCompleted

boolean

optional

Key that denotes if the activity was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam activities or not

limit

integer

optional,
range : 1-100

Number of activities to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: activityTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams,projects.

GET /api/v1/tickets/{ticket_id}/activities

OAuth Scope

Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , ~~Desk.calls.READ~~ , ~~Desk.tasks.READ~~ , ~~Desk.events.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/activities?include=tickets,contacts,assignee,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ActivityAPI activity = ZDesk.getActivityAPIInstance(mailId);
GetTicketActivitiesFilter filter = new GetTicketActivitiesFilter.Builder().setIsCompleted(isCompleted).build();
List<Activity> response = activity.getTicketActivities( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "35",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Stall in Dubai Airport",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e484b8a02355a7e402",
    "createdTime" : "2019-04-12T05:21:21.000Z",
    "startTime" : "2019-12-25T16:52:11.000Z",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "35",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000083048",
    "isSpam" : false,
    "category" : "Demo",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "direction" : "inbound",
    "status" : "Not Started"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "Steve",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Gadget Replacement",
    "completedTime" : "2019-04-17T07:12:09.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "createdTime" : "2019-04-10T10:30:55.000Z",
    "startTime" : "2019-04-11T06:30:00.000Z",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "35",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000081089",
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "direction" : "outbound",
    "status" : "Completed"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "Steve",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Rest OS Version",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-24T06:30:00.000Z",
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e40af0073cf7981c2f",
    "createdTime" : "2019-04-10T10:07:26.000Z",
    "startTime" : "2019-04-24T06:30:00.000Z",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000081036",
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "direction" : "inbound",
    "status" : "Not Started"
  } ]
}

Calls

Calls refer to the support-related calls your customers make to your help desk and vice versa. It is mandatory for each call to be mapped to a contact.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the call

~~customFields~~

deprecated

list

User-defined fields related to the call

list

User-defined fields related to the call

departmentId
see documentation

long

ID of the department associated with the call and ticket

subject

string

Subject of the call

startTime

timestamp

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

Direction of the call: inbound or outbound

duration

integer

Duration of the call in seconds

status

string

Completion status of the call

ownerId

long

ID of the user to whom the call is assigned

priority

string

Priority of the call

description

string

Description of the call

createdTime

timestamp

Time when the call entry was added

modifiedTime

timestamp

Time when details of the call entry were modified

creatorId

string

ID of user who created the call

ticketId
see documentation

long

ID of the ticket associated with the call

contactId

long

ID of the contact associated with the call

ticket

show Attributes

Ticket

Details of the ticket associated with the call

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "cf" : { }, "reminder" : [ { "alertType" : [ "EMAIL" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T10:32:11.000Z" }, { "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T16:32:11.000Z" }, { "relativeReminderInMin" : "10", "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "RELATIVE" } ], "contactId" : "3000000008749", "subject" : "New Call", "completedTime" : "2016-07-26T17:32:11.000Z", "departmentId" : "3000000007043", "creatorId" : "3000000008692", "description" : null, "ownerId" : "3000000015683", "priority" : "Normal", "duration" : "30", "createdTime" : "2016-07-25T17:32:11.000Z", "startTime" : "2016-07-25T16:52:11.000Z", "modifiedBy" : { "firstName" : "George", "lastName" : "McKinson", "photoURL" : null, "id" : "5000000015911" }, "id" : "3000000018001", "isSpam" : false, "ticketId" : "3000000008753", "status" : "completed", "direction" : "inbound" }

Get call

This API fetches the details of a call.

Mock API

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the call. Values allowed are: contacts, assignee,tickets,teams,livecalls.

GET api/v1/calls/{call_id}

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , ~~Desk.calls.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/calls/5000000081089?include=tickets,contacts,assignee,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CallAPI call = ZDesk.getCallAPIInstance(mailId);
Call response = call.getCall( callId, include );

Response Example

{
  "modifiedTime" : "2019-04-30T10:42:41.000Z",
  "subject" : "Call check scheduled",
  "completedTime" : "2019-04-17T07:12:09.000Z",
  "departmentId" : "5000000012710",
  "creatorId" : "5000000015911",
  "description" : null,
  "ownerId" : "5000000015911",
  "livecall" : {
    "recordings" : [ {
      "duration" : "84",
      "url" : "https://api.twilio.com/2010-04-01/Accounts/ACc3617ac782db73fcad51991c141243d6/Recordings/RE5ec62dec6cc69a9459e6ff8a096a7f31b"
    }, {
      "duration" : "675",
      "url" : "https://api.twilio.com/2010-04-01/Accounts/ACc3617ac782db73fcad51991c141243d6/Recordings/RE5ec62dec6cc69a9459e6ff8a096a7f23b"
    } ],
    "voiceMailDuration" : null,
    "id" : "6000000026017",
    "voiceMailUrl" : null
  },
  "duration" : "7380",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false
  },
  "createdTime" : "2019-04-10T10:30:55.000Z",
  "startTime" : "2019-04-11T06:30:00.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000081089",
  "direction" : "outbound",
  "cf" : {
  },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : null,
    "id" : "5000000016294",
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open"
  },
  "reminder" : [ {
    "alertType" : [ "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-24T06:30:00.000Z"
  }, {
    "alertType" : [ "SMS", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-23T06:30:00.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-22T06:30:00.000Z"
  } ],
  "contactId" : "5000000016252",
  "team" : null,
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "ticketId" : "5000000016294",
  "status" : "Completed"
}

List calls

This API fetches a particular number of calls, based on the limit specified.

Mock API

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the call. Values allowed are: contacts, assignee,tickets,teams.

from

integer

optional

Index number, starting from which the calls must be fetched

limit

integer

optional,
range : 1-100

Number of calls to fetch

departmentId
see documentation

long

optional

ID of the department from which the calls must be fetched

departmentIds
see documentation

long

optional

Departments from which the calls need to be queried

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

startTime

string

optional,
max chars : 100

Start time for completing the call. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

isCompleted

boolean

optional

Key that denotes whether the call is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the calls by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET api/v1/calls

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , ~~Desk.calls.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/calls?include=tickets,contacts,assignee,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CallAPI call = ZDesk.getCallAPIInstance(mailId);
GetCallsFilter filter = new GetCallsFilter.Builder().setViewId(viewId).build();
List<Call> response = call.getCalls( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticket" : null,
    "contactId" : null,
    "subject" : "hRl",
    "completedTime" : "2019-04-02T06:36:43.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e48740f9abf01f71bf",
    "contact" : null,
    "createdTime" : "2019-04-02T06:36:43.000Z",
    "startTime" : "2019-03-24T11:40:01.000Z",
    "id" : "5000000049385",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Canceled",
    "direction" : "inbound"
  }, {
    "ticket" : null,
    "contactId" : null,
    "subject" : "Irt",
    "completedTime" : "2019-04-02T06:37:06.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4603451fcf41c54b2",
    "contact" : null,
    "createdTime" : "2019-04-02T06:37:06.000Z",
    "startTime" : "2019-03-24T11:40:24.000Z",
    "id" : "5000000053840",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Canceled",
    "direction" : "inbound"
  }, {
    "ticket" : null,
    "contactId" : null,
    "subject" : "SG0",
    "completedTime" : "2019-04-02T06:36:28.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e46c76cc4bfd688f1b",
    "contact" : null,
    "createdTime" : "2019-04-02T06:36:28.000Z",
    "startTime" : "2019-04-01T11:39:44.000Z",
    "id" : "5000000047098",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Completed",
    "direction" : "inbound"
  } ]
}

Create call

This API adds a call entry to your help desk portal.

Mock API

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the call

list

optional

User-defined fields related to the call

departmentId
see documentation

long

required

ID of the department associated with the call and ticket

subject

string

required,
max chars : 300

Subject of the call

startTime

timestamp

required

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

required,
max chars : 100

Direction of the call: inbound or outbound

duration

integer

required

Duration of the call in seconds

status

string

required,
max chars : 120

Completion status of the call

ownerId

long

optional

ID of the user to whom the call is assigned

priority

string

optional,
max chars : 120

Priority of the call

description

string

optional,
max chars : 65535

Description of the call

ticketId
see documentation

long

optional

ID of the ticket associated with the call

contactId

long

required

ID of the contact associated with the call

reminder

JSONArray

optional

Details of the reminder associated with the call

POST api/v1/calls

OAuth Scope

Desk.activities.calls.CREATE , Desk.activities.CREATE , ~~Desk.calls.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/calls
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "duration" : "300", "reminder" : [ { "alertType" : [ "EMAIL", "SMS", "POPUP" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2018-12-25T04:52:13.000Z" } ], "contactId" : "1892000000088017", "subject" : "New Testing Call", "departmentId" : "3000000007043", "startTime" : "2016-07-25T16:52:11.000Z", "priority" : "High", "ticketId" : "3000000008753", "direction" : "inbound", "status" : "In Progress" }'

CallAPI call = ZDesk.getCallAPIInstance(mailId);
Call callObj = new Call();
callObj.setSubject(subject);
callObj.setDescription(description);
callObj.setDirection(direction);
callObj.setStatus(status);
Call response = call.createCall( callObj );

Response Example

{
  "cf" : {
  },
  "contactId" : "1892000000088017",
  "subject" : "New Testing Call",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "duration" : "300",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "startTime" : "2016-07-25T16:52:11.000Z",
  "id" : "3000000054002",
  "ticketId" : "3000000008753",
  "direction" : "inbound",
  "status" : "In Progress"
}

Update call

This API updates the details of a call.

Mock API

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the call

list

optional

User-defined fields related to the call

departmentId
see documentation

long

optional

ID of the department associated with the call and ticket

subject

string

optional,
max chars : 300

Subject of the call

startTime

timestamp

optional

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

optional,
max chars : 100

Direction of the call: inbound or outbound

duration

integer

optional

Duration of the call in seconds

status

string

optional,
max chars : 120

Completion status of the call

ownerId

long

optional

ID of the user to whom the call is assigned

priority

string

optional,
max chars : 120

Priority of the call

description

string

optional,
max chars : 65535

Description of the call

ticketId
see documentation

long

optional

ID of the ticket associated with the call

contactId

long

optional

ID of the contact associated with the call

reminder

JSONArray

optional

Details of the reminder associated with the call

PATCH api/v1/calls/{call_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , ~~Desk.calls.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/calls/3000000054002
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "contactId" : "30000000088017", "description" : "Call completed with a callback request", "status" : "completed" }'

Response Example

{
  "modifiedTime" : "2016-07-14T08:29:26.000Z",
  "cf" : {
  },
  "contactId" : "30000000088017",
  "subject" : "New Testing Call",
  "completedTime" : "2016-07-14T08:29:26.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : "Call completed with a callback request",
  "ownerId" : null,
  "priority" : "High",
  "duration" : "120",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000054002",
  "isSpam" : false,
  "ticketId" : "3000000008753",
  "direction" : "inbound",
  "status" : "completed"
}

List calls by ticket

This API lists a particular number of calls associated with a ticket, based on the limit specified.

Mock API

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the calls must be listed

isCompleted

boolean

optional

Key that denotes if the call was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam calls or not

limit

integer

optional,
range : 1-100

Number of calls to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams.

GET /api/v1/tickets/{ticket_id}/calls

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , ~~Desk.tickets.READ~~ , ~~Desk.calls.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/calls?include=tickets,contacts,assignee,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CallAPI call = ZDesk.getCallAPIInstance(mailId);
GetCallsByTicketFilter filter = new GetCallsByTicketFilter.Builder().setIsCompleted(isCompleted).build();
List<Call> response = call.getCallsByTicket( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "subject" : "Call check scheduled",
    "completedTime" : "2019-04-17T07:12:09.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-10T10:30:55.000Z",
    "startTime" : "2019-04-11T06:30:00.000Z",
    "id" : "5000000081089",
    "direction" : "outbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013468",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "status" : "Completed"
  }, {
    "subject" : "ddddd",
    "completedTime" : "2019-04-17T07:11:43.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4437f38846d520c51",
    "isCommented" : false,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-05T11:15:15.000Z",
    "startTime" : "2019-04-24T06:30:00.000Z",
    "id" : "5000000069105",
    "direction" : "outbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013468",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4437f38846d520c51",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "status" : "Completed"
  } ]
}

Delete calls

This API moves call entries to the Recycle Bin of your help desk portal.

Attributes

Param Name

Data Type

Description

entityIds

list

required

IDs of the activities to delete

POST /api/v1/calls/moveToTrash

OAuth Scope

Desk.activities.calls.DELETE , Desk.activities.DELETE , ~~Desk.calls.DELETE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/calls/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "entityIds" : [ "3000000053002" ]
}'

CallAPI call = ZDesk.getCallAPIInstance(mailId);
boolean response = call.moveToTrash( entityIds );

Response Example

Clear live call mapping from an activity

This API clears the live call mapping from an activity

POST /api/v1/calls/{call_id}/clearLiveCall

OAuth Scope

Desk.calls.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/calls/{call_id}/clearLiveCall
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Update many calls

This API updates multiple calls at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/calls/updateMany

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , ~~Desk.calls.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/calls/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "mobile", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "8508569875" }'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Calls Comments

Call comments refer to comments recorded on calls assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a call comment

This API adds a comment to a call.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/calls/{call_id}/comments

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/calls/4000000530001/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First Call comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Call comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a call comment

This API updates an existing call comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "Edit Call comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Call comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a call comment

This API deletes an existing call comment.

DELETE api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
boolean response = comment.deleteCallComment( callId, commentId );

Response Example

Get a call comment

This API fetches a call comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530005
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getCallComment( callId, commentId, include );

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Call Comment......",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all call comments

This API lists a particular number of comments recorded on a call, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/calls/{call_id}/comments

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/calls/4000000530001/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getCallComments( callId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Second Call Comment......",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Call comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Events

Events refer to pre-planned, and most of the time, directly customer-facing activities aimed at ticket resolution. The different events supported in Zoho Desk are: meetings and demos.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the event

~~customFields~~

deprecated

list

User-defined fields related to the event

list

User-defined fields related to the event

departmentId
see documentation

long

ID of the department associated with the event and ticket

subject

string

Subject of the event

startTime

timestamp

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

Duration of the event in seconds

status

string

Completion status of the event

ownerId

long

ID of the user to whom the event is assigned

priority

string

Priority of the event

description

string

Description of the event

createdTime

timestamp

Time when the event entry was added

modifiedTime

timestamp

Time when details of the event entry were modified

creatorId

string

ID of the user who created the event

category

string

Category of the event

ticketId
see documentation

long

ID of the ticket associated with the event

contactId

long

ID of the contact associated with the event

ticket

show Attributes

Ticket

Details of the ticket associated with the event

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "cf" : { }, "reminder" : [ { "alertType" : [ "EMAIL" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T10:32:11.000Z" }, { "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "ABSOLUTE", "reminderTime" : "2016-07-26T16:32:11.000Z" }, { "relativeReminderInMin" : "10", "alertType" : [ "EMAIL", "POPUP" ], "reminderType" : "RELATIVE" } ], "contactId" : "3000000008749", "subject" : "Conference with Tech leads", "completedTime" : "2016-07-26T17:32:11.000Z", "departmentId" : "3000000007043", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "duration" : "30", "createdTime" : "2016-07-26T16:32:11.000Z", "modifiedBy" : { "firstName" : "George", "lastName" : "McKinson", "photoURL" : null, "id" : "5000000015911" }, "startTime" : "2016-07-26T17:02:11.000Z", "id" : "3000000018001", "isSpam" : false, "category" : "Meeting", "ticketId" : "3000000008753", "status" : "completed" }

Get event

This API fetches the details of an event.

Mock API

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams.

GET api/v1/events/{event_id}

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , ~~Desk.events.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/events/5000000065115?include=tickets?include=assignee,tickets,contacts,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

EventAPI event = ZDesk.getEventAPIInstance(mailId);
Event response = event.getEvent( eventId, include );

Response Example

{
  "modifiedTime" : "2019-04-30T14:22:13.000Z",
  "subject" : "Zoholics 2019",
  "completedTime" : null,
  "departmentId" : "5000000012710",
  "creatorId" : "5000000015911",
  "description" : null,
  "ownerId" : "5000000015911",
  "secId" : "9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
  "duration" : "10980",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false,
    "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
  },
  "createdTime" : "2019-04-04T06:48:36.000Z",
  "startTime" : "2019-04-18T06:30:00.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000065115",
  "cf" : {
  },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : null,
    "id" : "5000000016294",
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open",
    "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
  },
  "reminder" : null,
  "contactId" : "5000000016252",
  "team" : null,
  "priority" : "High",
  "layoutId" : "5000000013470",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
  "teamId" : null,
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "5000000016294",
  "status" : "Not Started"
}

Get event

This API lists a particular number of events, based on the limit specified.

Mock API

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Additional information related to the event. Values allowed are: contacts, assignee,tickets,teams.

from

integer

optional

Index number, starting from which the events must be fetched

limit

integer

optional,
range : 1-100

Number of events to list

startTime

string

optional,
max chars : 100

Start time for completing the event. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

departmentId
see documentation

long

optional

ID of the department from which the events must be fetched

departmentIds
see documentation

long

optional

Departments from which the events need to be queried

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

isCompleted

boolean

optional

Key that denotes whether the event is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the events by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET api/v1/events

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , ~~Desk.events.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/events?include=assignee,tickets,contacts,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

EventAPI event = ZDesk.getEventAPIInstance(mailId);
GetEventsFilter filter = new GetEventsFilter.Builder().setViewId(viewId).build();
List<Event> response = event.getEvents( from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Partner's conference'",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false
    },
    "createdTime" : "2019-04-04T06:48:36.000Z",
    "startTime" : "2019-04-18T06:30:00.000Z",
    "id" : "5000000065115",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started",
    "direction" : "inbound"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Developers meet",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e41c8e46db1a43ba49",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false
    },
    "createdTime" : "2019-04-16T12:02:27.000Z",
    "startTime" : "2019-04-25T06:30:00.000Z",
    "id" : "5000000084070",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started",
    "direction" : "inbound"
  } ]
}

Create event

This API adds an event entry to your help desk portal.

Mock API

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the event

list

optional

User-defined fields related to the event

departmentId
see documentation

long

required

ID of the department associated with the event and ticket

subject

string

required,
max chars : 300

Subject of the event

startTime

timestamp

required

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

required

Duration of the event in seconds

status

string

optional,
max chars : 120

Completion status of the event

ownerId

long

optional

ID of the user to whom the event is assigned

priority

string

optional,
max chars : 120

Priority of the event

description

string

optional,
max chars : 65535

Description of the event

category

string

optional,
max chars : 120

Category of the event

ticketId
see documentation

long

optional

ID of the ticket associated with the event

contactId

long

required

ID of the contact associated with the event

reminder

JSONArray

optional

Details of the reminder associated with the event

POST api/v1/events

OAuth Scope

Desk.activities.events.CREATE , Desk.activities.CREATE , ~~Desk.events.CREATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/events
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "duration" : "40", "contactId" : "3000000001234", "subject" : "Dubai startup meet", "departmentId" : "3000000007043", "startTime" : "2016-07-14T08:27:26.000Z", "priority" : "High", "category" : "Meeting", "ticketId" : "3000000008753", "status" : "In Progress" }'

EventAPI event = ZDesk.getEventAPIInstance(mailId);
Event eventObj = new Event();
eventObj.setSubject(subject);
eventObj.setDescription(description);
eventObj.setWebUrl(webUrl);
eventObj.setCategory(category);
Event response = event.createEvent( eventObj );

Response Example

{
  "cf" : {
  },
  "contactId" : "3000000001234",
  "subject" : "New Testing Event",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "duration" : "40",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "startTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Update event

This API updates the details of an event.

Mock API

Attributes

Param Name

Data Type

Description

~~customFields~~

deprecated

list

optional

User-defined fields related to the event

list

optional

User-defined fields related to the event

departmentId
see documentation

long

optional

ID of the department associated with the event and ticket

subject

string

optional,
max chars : 300

Subject of the event

startTime

timestamp

optional

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

optional

Duration of the event in seconds

status

string

optional,
max chars : 120

Completion status of the event

ownerId

long

optional

ID of the user to whom the event is assigned

priority

string

optional,
max chars : 120

Priority of the event

description

string

optional,
max chars : 65535

Description of the event

category

string

optional,
max chars : 120

Category of the event

ticketId
see documentation

long

optional

ID of the ticket associated with the event

contactId

long

optional

ID of the contact associated with the event

reminder

JSONArray

optional

Details of the reminder associated with the event

PATCH api/v1/events/{event_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , ~~Desk.events.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/events/3000000054002
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "contactId" : "30000000088017", "description" : "Event completed with a callback request", "status" : "completed" }'

Response Example

{
  "modifiedTime" : "2016-07-14T08:47:26.000Z",
  "cf" : {
  },
  "contactId" : "30000000088017",
  "subject" : "Event camp at Finland",
  "completedTime" : "2016-07-14T08:47:26.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : "Event completed with a callback request",
  "ownerId" : null,
  "priority" : "High",
  "duration" : "20",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "startTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "completed"
}

List events by ticket

This API lists a particular number of events associated with a ticket, based on the limit specified.

Mock API

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the events must be listed

isCompleted

boolean

optional

Key that denotes if the event was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam events or not

limit

integer

optional,
range : 1-100

Number of events to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams.

GET /api/v1/tickets/{ticket_id}/events

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , ~~Desk.tickets.READ~~ , ~~Desk.events.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/events?include=assignee,tickets,contacts,teams
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

EventAPI event = ZDesk.getEventAPIInstance(mailId);
GetEventsByTicketFilter filter = new GetEventsByTicketFilter.Builder().setIsCompleted(isCompleted).build();
List<Event> response = event.getEventsByTicket( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "subject" : "Zoholics at Australia",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-04T06:48:36.000Z",
    "startTime" : "2019-04-18T06:30:00.000Z",
    "id" : "5000000065115",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013470",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started"
  }, {
    "subject" : "sadfsadf",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e41c8e46db1a43ba49",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-16T12:02:27.000Z",
    "startTime" : "2019-04-25T06:30:00.000Z",
    "id" : "5000000084070",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013470",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e41c8e46db1a43ba49",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started"
  } ]
}

Delete events

This API moves event entries to the Recycle Bin of your help desk portal.

Attributes

Param Name

Data Type

Description

entityIds

list

required

IDs of the activities to delete

POST /api/v1/events/moveToTrash

OAuth Scope

Desk.activities.events.DELETE , Desk.activities.DELETE , ~~Desk.events.DELETE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/events/moveToTrash
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "entityIds" : [ "3000000053002" ]
}'

EventAPI event = ZDesk.getEventAPIInstance(mailId);
boolean response = event.moveToTrash( entityIds );

Response Example

Update many events

This API updates multiple events at once.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the entities to update

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/events/updateMany

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , ~~Desk.events.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/events/updateMany
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "fieldName" : "mobile", "isCustomField" : false, "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ], "fieldValue" : "8508569875" }'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Events Comments

Event comments refer to comments recorded on events assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

show Attributes

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "contentType" : "html", "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing", "commenterId" : "1892000000042001", "mention" : [ { "firstName" : "", "lastName" : "pandees", "photoURL" : null, "offSet" : "7", "length" : "28", "id" : "31138000000573164", "type" : "AGENT", "email" : "jade15tywin@zylker.com", "zuid" : "55616589" }, { "offSet" : "39", "length" : "46", "name" : "new team", "id" : "31138000001254025", "type" : "TEAM" }, { "offSet" : "59", "departmentId" : "3113800000634345", "entityNumber" : "1342", "length" : "26", "name" : "", "id" : "3113800000143134", "type" : "TICKET" } ], "commenter" : { "firstName" : "Jade", "lastName" : "Tywin", "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo", "name" : "Jade Tywin", "roleName" : "PortalUser", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

Create a event comment

This API adds a comment to a event.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/events/{event_id}/comments

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/events/4000000530001/comments
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "contentType" : "html",
  "content" : "First Event comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Event comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a event comment

This API updates an existing event comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "content" : "Edit Event comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Event comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a event comment

This API deletes an existing event comment.

DELETE api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , ~~Desk.tasks.UPDATE~~

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
boolean response = comment.deleteEventComment( eventId, commentId );

Response Example

Get a event comment

This API fetches a event comment from the portal.

Query Params

Param Name

Data Type

Description

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530005?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
Comment response = comment.getEventComment( eventId, commentId, include );

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Event Comment......",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all event comments

This API lists a particular number of comments recorded on a event, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/events/{event_id}/comments

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , ~~Desk.tasks.READ~~

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/events/4000000530001/comments?include=mentions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

CommentAPI comment = ZDesk.getCommentAPIInstance(mailId);
List<Comment> response = comment.getEventComments( eventId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Event comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Modules

The Modules Present in the helpdesk

Example

{ "displayLabel" : "Tickets", "apiKey" : "tickets", "isEnabled" : true, "pluralLabel" : "Tickets", "id" : "127254000000000177", "singularLabel" : "Ticket" }

List All Modules

This API is to fetch the modules that are available for listing in Zoho Desk.

GET /api/v1/modules

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/modules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ModuleAPI module = ZDesk.getModuleAPIInstance(mailId);
List<Module> response = module.getModules( );

Response Example

{
  "modules" : [ {
    "displayLabel" : "Contracts",
    "apiKey" : "contracts",
    "isEnabled" : false,
    "pluralLabel" : "Contracts",
    "id" : "127254000000000183",
    "singularLabel" : "Contract"
  }, {
    "displayLabel" : "Topics",
    "apiKey" : "category",
    "isEnabled" : false,
    "pluralLabel" : "Topics",
    "id" : "127254000000000195",
    "singularLabel" : "Topic"
  }, {
    "displayLabel" : "Time Entry1",
    "apiKey" : "timeEntry",
    "isEnabled" : false,
    "pluralLabel" : "Time Entry1",
    "id" : "127254000000000187",
    "singularLabel" : "Time Entry"
  }, {
    "displayLabel" : "Help Center",
    "apiKey" : "kbCategory",
    "isEnabled" : true,
    "pluralLabel" : "ArticleA",
    "id" : "127254000000000181",
    "singularLabel" : "Article"
  }, {
    "displayLabel" : "Social",
    "apiKey" : "social",
    "isEnabled" : true,
    "pluralLabel" : "Social",
    "id" : "127254000000024005",
    "singularLabel" : "Social"
  }, {
    "displayLabel" : "Community",
    "apiKey" : "community",
    "isEnabled" : true,
    "pluralLabel" : "Community",
    "id" : "127254000000015001",
    "singularLabel" : "Community"
  }, {
    "displayLabel" : "Tasks",
    "apiKey" : "tasks",
    "isEnabled" : true,
    "pluralLabel" : "Tasks",
    "id" : "127254000000000171",
    "singularLabel" : "Task"
  }, {
    "displayLabel" : "Tickets",
    "apiKey" : "tickets",
    "isEnabled" : true,
    "pluralLabel" : "Tickets",
    "id" : "127254000000000177",
    "singularLabel" : "Ticket"
  }, {
    "displayLabel" : "Contacts",
    "apiKey" : "contacts",
    "isEnabled" : true,
    "pluralLabel" : "Contacts",
    "id" : "127254000000000161",
    "singularLabel" : "Contact"
  }, {
    "displayLabel" : "Products",
    "apiKey" : "products",
    "isEnabled" : true,
    "pluralLabel" : "Products",
    "id" : "127254000000000185",
    "singularLabel" : "Product"
  }, {
    "displayLabel" : "zAccounts",
    "apiKey" : "accounts",
    "isEnabled" : true,
    "pluralLabel" : "zAccounts",
    "id" : "127254000000000159",
    "singularLabel" : "Account"
  }, {
    "displayLabel" : "Chat",
    "apiKey" : "chat",
    "isEnabled" : true,
    "pluralLabel" : "Chat",
    "id" : "127254000000032011",
    "singularLabel" : "Chat"
  }, {
    "displayLabel" : "Reports",
    "apiKey" : "reports",
    "isEnabled" : true,
    "pluralLabel" : "Reports",
    "id" : "127254000000000163",
    "singularLabel" : "Report"
  }, {
    "displayLabel" : "Dashboards",
    "apiKey" : "dashboards",
    "isEnabled" : true,
    "pluralLabel" : "Dashboards",
    "id" : "127254000000000165",
    "singularLabel" : "Dashboard"
  } ]
}

List Modules accessible to me

This API will fetch the list of modules that are accessible to the current user profile.

GET /api/v1/myAccessibleModules

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/modules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ModuleAPI module = ZDesk.getModuleAPIInstance(mailId);
List<Module> response = module.getMyModules( );

Response Example

{
  "modules" : [ {
    "displayLabel" : "Contracts",
    "apiKey" : "contracts",
    "isEnabled" : false,
    "pluralLabel" : "Contracts",
    "id" : "127254000000000183",
    "singularLabel" : "Contract"
  }, {
    "displayLabel" : "Topics",
    "apiKey" : "category",
    "isEnabled" : false,
    "pluralLabel" : "Topics",
    "id" : "127254000000000195",
    "singularLabel" : "Topic"
  }, {
    "displayLabel" : "Time Entry1",
    "apiKey" : "timeEntry",
    "isEnabled" : false,
    "pluralLabel" : "Time Entry1",
    "id" : "127254000000000187",
    "singularLabel" : "Time Entry"
  }, {
    "displayLabel" : "Help Center",
    "apiKey" : "kbCategory",
    "isEnabled" : true,
    "pluralLabel" : "ArticleA",
    "id" : "127254000000000181",
    "singularLabel" : "Article"
  }, {
    "displayLabel" : "Social",
    "apiKey" : "social",
    "isEnabled" : true,
    "pluralLabel" : "Social",
    "id" : "127254000000024005",
    "singularLabel" : "Social"
  }, {
    "displayLabel" : "Community",
    "apiKey" : "community",
    "isEnabled" : true,
    "pluralLabel" : "Community",
    "id" : "127254000000015001",
    "singularLabel" : "Community"
  }, {
    "displayLabel" : "Tasks",
    "apiKey" : "tasks",
    "isEnabled" : true,
    "pluralLabel" : "Tasks",
    "id" : "127254000000000171",
    "singularLabel" : "Task"
  }, {
    "displayLabel" : "Tickets",
    "apiKey" : "tickets",
    "isEnabled" : true,
    "pluralLabel" : "Tickets",
    "id" : "127254000000000177",
    "singularLabel" : "Ticket"
  }, {
    "displayLabel" : "Contacts",
    "apiKey" : "contacts",
    "isEnabled" : true,
    "pluralLabel" : "Contacts",
    "id" : "127254000000000161",
    "singularLabel" : "Contact"
  }, {
    "displayLabel" : "Products",
    "apiKey" : "products",
    "isEnabled" : true,
    "pluralLabel" : "Products",
    "id" : "127254000000000185",
    "singularLabel" : "Product"
  }, {
    "displayLabel" : "zAccounts",
    "apiKey" : "accounts",
    "isEnabled" : true,
    "pluralLabel" : "zAccounts",
    "id" : "127254000000000159",
    "singularLabel" : "Account"
  }, {
    "displayLabel" : "Chat",
    "apiKey" : "chat",
    "isEnabled" : true,
    "pluralLabel" : "Chat",
    "id" : "127254000000032011",
    "singularLabel" : "Chat"
  }, {
    "displayLabel" : "Reports",
    "apiKey" : "reports",
    "isEnabled" : true,
    "pluralLabel" : "Reports",
    "id" : "127254000000000163",
    "singularLabel" : "Report"
  }, {
    "displayLabel" : "Dashboards",
    "apiKey" : "dashboards",
    "isEnabled" : true,
    "pluralLabel" : "Dashboards",
    "id" : "127254000000000165",
    "singularLabel" : "Dashboard"
  } ]
}

OrganizationFields

Account refers to customer organizations that use your products or services. An account can have multiple contacts.

ATTRIBUTES

Attribute Name

Data Type

Description

displayLabel

string

Name of the field on the UI

~~name~~

deprecated

string

Name of the custom field

apiName

string

Unique readonly name of the custom field that can be used to update value of record in api

i18NLabel

string

i18nlabel for the field label

type

string

Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, and Boolean

maxLength

integer

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

Precision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields

roundingOption

string

Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp

defaultValue

string

Default value set for a field. Applicable for Checkbox fields

allowedValues

list

Values allowed in a field. Applicable for PickList fields

Example

{ "displayLabel" : "Department", "apiName" : "departmentId", "isCustomField" : false, "showToHelpCenter" : true, "isEncryptedField" : false, "id" : "4000000000353", "type" : "LookUp", "maxLength" : 50, "isMandatory" : false }

Get organization fields in a module

This API fetches fields in a module

Query Params

Param Name

Data Type

Description

module

String

required

the module name with in which search to be done. Value may be tickets, contacts , accounts ,tasks , calls , events, timeEntry,products, contracts

apiNames

string

optional,
max chars : 100

Key that fetches only the fields whose apiNames are given. Multiple values can be passed, with commas for separation.

departmentId
see documentation

long

optional

Key that fetches only the fields for the given departmentId.

GET /api/v1/organizationFields

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields?module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

FieldAPI field = ZDesk.getFieldAPIInstance(mailId);
List<Field> response = field.getFields(module, apiNames );

Response Example

{
  "data" : [ {
    "displayLabel" : "Department",
    "apiName" : "departmentId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000353",
    "type" : "LookUp",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Account Name",
    "apiName" : "accountId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000355",
    "type" : "LookUp",
    "maxLength" : 300,
    "isMandatory" : false
  }, {
    "displayLabel" : "Contact Name",
    "apiName" : "contactId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000357",
    "type" : "LookUp",
    "maxLength" : 300,
    "isMandatory" : true
  }, {
    "displayLabel" : "Email",
    "apiName" : "email",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000359",
    "type" : "Email",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Phone",
    "apiName" : "phone",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000361",
    "type" : "Phone",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Subject",
    "apiName" : "subject",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000363",
    "type" : "Text",
    "maxLength" : 255,
    "isMandatory" : true
  }, {
    "displayLabel" : "Description",
    "apiName" : "description",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000365",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ {
      "statusType" : "Open",
      "value" : "Open"
    }, {
      "statusType" : "Open",
      "value" : "Open_july"
    }, {
      "statusType" : "Open",
      "value" : "Open_newDept"
    }, {
      "statusType" : "On Hold",
      "value" : "On Hold"
    }, {
      "statusType" : "Open",
      "value" : "Escalated"
    }, {
      "statusType" : "Closed",
      "value" : "Closed1"
    }, {
      "statusType" : "Open",
      "value" : "Closed"
    }, {
      "statusType" : "Closed",
      "value" : "newDeptClosed"
    }, {
      "statusType" : "Closed",
      "value" : "julyDeptClosed"
    }, {
      "statusType" : "Closed",
      "value" : "julyDeptClosed1"
    } ],
    "apiName" : "status",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000367",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : true
  }, {
    "displayLabel" : "Product Name",
    "apiName" : "productId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000369",
    "type" : "LookUp",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Case Owner",
    "apiName" : "assigneeId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000371",
    "type" : "LookUp",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Category",
    "allowedValues" : [ {
      "value" : "General"
    }, {
      "value" : "Defects"
    }, {
      "value" : "ManojKumar"
    } ],
    "apiName" : "category",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000421",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Sub Category",
    "allowedValues" : [ {
      "value" : "Sub General"
    }, {
      "value" : "Sub Defects"
    }, {
      "value" : "Sub Defects1235"
    } ],
    "apiName" : "subCategory",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000423",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Due Date",
    "apiName" : "dueDate",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000405",
    "type" : "DateTime",
    "maxLength" : 300,
    "isMandatory" : false
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ {
      "value" : "-None-"
    }, {
      "value" : "High"
    }, {
      "value" : "Medium"
    }, {
      "value" : "Low"
    } ],
    "apiName" : "priority",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000407",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Mode",
    "allowedValues" : [ {
      "value" : "Phone"
    }, {
      "value" : "Email"
    }, {
      "value" : "Web"
    }, {
      "value" : "Twitter"
    }, {
      "value" : "Facebook"
    }, {
      "value" : "Chat"
    }, {
      "value" : "Forums"
    }, {
      "value" : "Feedback Widget"
    } ],
    "apiName" : "channel",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000409",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Is Overdue",
    "apiName" : "Is Overdue",
    "isCustomField" : false,
    "defaultValue" : "true",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000411",
    "type" : "Boolean",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Is Escalated",
    "apiName" : "Is Escalated",
    "isCustomField" : false,
    "defaultValue" : "true",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000413",
    "type" : "Boolean",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Classification",
    "allowedValues" : [ {
      "value" : "-None-"
    }, {
      "value" : "Question"
    }, {
      "value" : "Problem"
    }, {
      "value" : "Feature"
    }, {
      "value" : "Others"
    } ],
    "apiName" : "classification",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000415",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Resolution",
    "apiName" : "resolution",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000417",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  }, {
    "displayLabel" : "Sample Text Field",
    "apiName" : "cf_sample_text_field",
    "isCustomField" : false,
    "toolTipType" : "placeHolder",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "toolTip" : "Sample Text Field",
    "id" : "4000000000447",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  } ]
}

Create Field

This API creates a field

Query Params

Param Name

Data Type

Description

module

String

required

Name of the module whose fields must be fetched. Values allowed are tickets, contacts, accounts, tasks, timeEntry, products , calls , events, and contracts.

Attributes

Param Name

Data Type

Description

displayLabel

string

required,
max chars : 200

Name of the field on the UI

~~name~~

deprecated

string

optional,
max chars : 200

Name of the custom field

type

string

required,
max chars : 100

Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, and Boolean

maxLength

integer

optional

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

optional

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

optional

Precision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields

roundingOption

string

optional,
max chars : 120

Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields

allowedValues

list

optional

Values allowed in a field. Applicable for PickList fields

layoutIds

list

optional

IDs of layouts configured for the module

isEncryptedField

boolean

optional

Key that returns if the value in the field is encrypted or not. The field types are Text, Number, Percent, Decimal, Email, Phone, URL which supports encryption

toolTip

string

optional,
max chars : 200

the tool tip of the field

toolTipType

string

optional,
max chars : 200

the tool tip of the field

POST /api/v1/organizationFields

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/organizationFields?module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "displayLabel" : "Sample Text Field", "toolTipType" : "placeHolder", "showToHelpCenter" : true, "isEncryptedField" : true, "toolTip" : "Sample Text Field", "type" : "Text", "maxLength" : "50" }'

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : true,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 50,
  "isMandatory" : false
}

Edit Field

This API edits a field

Attributes

Param Name

Data Type

Description

displayLabel

string

optional,
max chars : 200

Name of the field on the UI

~~name~~

deprecated

string

optional,
max chars : 200

Name of the custom field

type

string

optional,
max chars : 100

Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, and Boolean

maxLength

integer

optional

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

optional

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

optional

Precision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields

roundingOption

string

optional,
max chars : 120

Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields

allowedValues

list

optional

Values allowed in a field. Applicable for PickList fields

layoutIds

list

optional

IDs of layouts configured for the module

isEncryptedField

boolean

optional

Key that returns if the value in the field is encrypted or not. The field types are Text, Number, Percent, Decimal, Email, Phone, URL which supports encryption

toolTip

string

optional,
max chars : 200

the tool tip of the field

toolTipType

string

optional,
max chars : 200

the tool tip of the field

PATCH /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/organizationFields/4000000049001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "displayLabel" : "Sample Text Field", "toolTipType" : "placeHolder", "showToHelpCenter" : false, "toolTip" : "Sample Text Field", "type" : "Text", "maxLength" : "40" }'

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : false,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 40,
  "isMandatory" : false
}

Get Field

This API get a field

GET /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields/4000000049001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : false,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 40,
  "isMandatory" : false
}

Get Field Permissions

This API get a field permissions for all the profiles

GET /api/v1/organizationFields/{field_id}/permissions

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields/4000000049001/permissions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

FieldAPI field = ZDesk.getFieldAPIInstance(mailId);
List<FieldPermission> response = field.getFieldPermissions( fieldId );

Response Example

{
  "data" : [ {
    "profileName" : "Administrator",
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Standard",
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Supervisor",
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Support Manager",
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Newbie Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Light Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  } ]
}

Update Field Permissions

This API update field permissions

Attributes

Param Name

Data Type

Description

profiles

list

optional

null

PATCH /api/v1/organizationFields/{field_id}/permissions

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/organizationFields/4000000049001/permissions
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "profiles" : [ {
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isWriteOnly" : true
  } ]
}'

Response Example

{
  "data" : [ {
    "profileName" : "Administrator",
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Standard",
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Supervisor",
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Support Manager",
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Newbie Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Light Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  } ]
}

Delete Field

This API delete a custom field

DELETE /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/organizationFields/4000000049001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get organization custom fields count in a module

This API returns the custom field count allowed and available in a module.

Query Params

Param Name

Data Type

Description

module

String

required

Name of the module whose allowed and available custom fields must be fetched. Values allowed are tickets, contacts, accounts, tasks, calls, events, timeEntry, products, and contracts.

GET /api/v1/customFieldCount

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/customFieldCount?module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "customFieldCounts" : [ {
    "types" : [ "Text", "PickList", "Email", "Phone", "Website" ],
    "maximumLimit" : 100,
    "available" : 100,
    "type" : "Varchar"
  }, {
    "types" : [ "Textarea", "Multiselect" ],
    "maximumLimit" : 30,
    "available" : 30,
    "type" : "Text"
  }, {
    "types" : [ "Number" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Integer"
  }, {
    "types" : [ "Percent", "Decimal", "Currency" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Double"
  }, {
    "types" : [ "Date" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Date"
  }, {
    "types" : [ "DateTime" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "DateTime"
  }, {
    "types" : [ "Checkbox" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Boolean"
  }, {
    "types" : [ "Text", "Website", "Email", "Number", "Phone", "Percent", "Decimal" ],
    "maximumLimit" : 10,
    "available" : 10,
    "type" : "DESK_SEARCHABLE_CTEXT_OEK"
  }, {
    "maximumLimit" : 10,
    "available" : 10,
    "type" : "Formula"
  } ],
  "totalAvailableCount" : 230
}

Get organization custom fields criteria references

This API fetches criteria references of a custom field

Query Params

Param Name

Data Type

Description

featureType

String

required

Feature name from which criteria references has to be fetched - DirectAssignment, RoundRobin, WorkFlow, SLA, Supervise, BluePrint, CustomView, Report, GameTrophy, GameBadge, LayoutRules, ValidationRules

from

integer

required,
default : 0,
range : >=0

Index number, starting from which the rules must be listed

limit

integer

required,
default : 50,
range : 1-50

Number of references to fetch

GET /api/v1/organizationFields/{field_id}/criteriaReferences

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://support.zoho.com/api/v1/organizationFields/4000000049001/criteriaReferences?featureType=DirectAssignment&from=0&limit30
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "DirectAssignment" : [ {
    "encryptedId" : "c50bd2066db398caace9491e3010e657",
    "name" : "DA Rule1",
    "id" : 21000000057136
  }, {
    "encryptedId" : "c50bd2066db398caace9491e789a5cb3",
    "name" : "DA Rule2",
    "id" : 21000000067146
  } ]
}

Layouts

Layouts define the arrangement and necessity of fields in forms used to capture details of help desk resources: Tickets, Tasks, Contacts, and so on. Each department can have unique layouts with both default and custom fields. You can also determine the visibility settings for each field in a layout.

ATTRIBUTES

Attribute Name

Data Type

Description

long

ID of the layout

createdBy

long

ID of user who created the layout

modifiedBy

long

ID of user who modified the layout

departmentId

long

ID of department in which the layout is configured

createdTime

timestamp

Time of creating the layout

modifiedTime

timestamp

Time of modifying the layout

isDefaultLayout

boolean

Key that returns if the layout is the default layout in the module

layoutName

string

Name of the layout

layoutDesc

string

Description of the layout

layoutDisplayName

string

Display Name of the layout in HelpCenter

sections

show Attributes

list

sections in the layout

long

ID of the section

isCustomSection

boolean

Key that returns if the section is a user-defined section

name

null

Name of the section

i18NLabel

string

i18nlabel for the section name

fields

show Attributes

list

Fields in the section

name

string

Name of the key that refers to the field

apiName

string

Unique readonly name of the custom field that can be used to update value of record in api

i18NLabel

string

i18nlabel for the field label

displayLabel

string

Name of the field on the UI

type

string

Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, and Boolean

maxLength

integer

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

Precision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields

roundingOption

string

Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp

isSystemMandatory

boolean

Key that returns if a built-in field in the system is mandatory in the layout or not

isRemovable

boolean

Key that returns if the field can be deleted or not

isCustomField

boolean

Key that returns if the field is user-defined or not

isEncryptedField

boolean

Key that returns if the value in the field is encrypted or not

long

ID of the field in the layout

isMandatory

boolean

Key that returns if a field is mandatory in a layout or not

defaultValue

string

Default value set for a field. Applicable for Checkbox fields and PickList fields

allowedValues

show Attributes

list

Values allowed in a field. Applicable for PickList fields

restoreOnReplyValues

list

Values in the Status field which are set to fall back to the default value

sortBy

string

Key that sorts values in a PickList field either alphabetically or by a user-defined order

Example

{ "modifiedTime" : "2017-07-01T07:36:04.000Z", "skipDeptAccessValidation" : false, "layoutProfiles" : [ { "profileName" : "Support Administrator", "isDefault" : true, "id" : 4000000015183, "type" : "ADMIN" }, { "profileName" : "Agent", "isDefault" : true, "id" : 4000000015186, "type" : "STANDARD" }, { "profileName" : "Help Center", "isDefault" : true, "id" : 4000000015189, "type" : "PORTAL" }, { "profileName" : "Supervisor", "isDefault" : false, "id" : "4000000015192", "type" : "CUSTOM" }, { "profileName" : "Support Manager", "isDefault" : false, "id" : "4000000015195", "type" : "CUSTOM" }, { "profileName" : "Newbie Agent", "isDefault" : false, "id" : "4000000015198", "type" : "CUSTOM" }, { "profileName" : "Light Agent", "isDefault" : true, "id" : "4000000015201", "type" : "LIGHT" } ], "createdBy" : "4000000009118", "departmentId" : "4000000007175", "layoutDisplayName" : "Default Ticket Layout", "createdTime" : "2017-07-01T07:36:04.000Z", "modifiedBy" : "", "id" : "4000000007177", "isDefaultLayout" : true, "layoutDesc" : "Layout for the ticket module", "layoutName" : "Default Ticket Layout" }

List Layouts

This API lists all the layouts configured for a module.

Query Params

Param Name

Data Type

Description

module

String

required

Name of the module whose layouts must be fetched. Values allowed are tickets, contacts, accounts , calls , events, tasks, timeEntry, products, and contracts.

departmentId
see documentation

long

optional

ID of the department in which the layouts are configured

status

String

required,
default : active

Status of the layout Values allowed are active|inactive|all

from

integer

required,
default : 0

from index

limit

integer

required,
default : 20

no of layouts to be fetched

layoutName

string

optional,
max chars : 200

Name of the layout used as the keyword for the search

GET /api/v1/layouts

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts?module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

LayoutAPI layout = ZDesk.getLayoutAPIInstance(mailId);
GetLayoutsFilter filter = new GetLayoutsFilter.Builder().setModule(module).build();
List<Layout> response = layout.getLayouts( from, limit, filter );

Response Example

{
  "data" : [ {
    "modifiedTime" : "2019-05-09T06:24:10.000Z",
    "departmentId" : "4000000012710",
    "module" : "Cases",
    "layoutDisplayName" : "New Layout For Tickets",
    "layoutDesc" : "DESC",
    "isDefaultLayout" : true,
    "layoutName" : "New Layout For Tickets",
    "skipDeptAccessValidation" : false,
    "layoutProfiles" : [ {
      "profileName" : "Support Administrator",
      "isDefault" : true,
      "id" : "4000000015183",
      "type" : "ADMIN"
    }, {
      "profileName" : "Agent",
      "isDefault" : true,
      "id" : "4000000015186",
      "type" : "STANDARD"
    }, {
      "profileName" : "Help Center",
      "isDefault" : true,
      "id" : "4000000015189",
      "type" : "PORTAL"
    } ],
    "createdBy" : "4000000015894",
    "createdTime" : "2019-05-03T06:36:33.000Z",
    "modifiedBy" : "4000000015894",
    "id" : "4000000013464",
    "status" : "active"
  }, {
    "modifiedTime" : "2019-05-06T01:45:58.000Z",
    "departmentId" : "4000000012710",
    "module" : "Cases",
    "layoutDisplayName" : "cloneLayout",
    "layoutDesc" : "DESC",
    "isDefaultLayout" : false,
    "layoutName" : "cloneLayout",
    "skipDeptAccessValidation" : false,
    "layoutProfiles" : [ {
      "profileName" : "Support Administrator",
      "isDefault" : true,
      "id" : "4000000015183",
      "type" : "ADMIN"
    }, {
      "profileName" : "Agent",
      "isDefault" : true,
      "id" : "4000000015186",
      "type" : "STANDARD"
    }, {
      "profileName" : "Help Center",
      "isDefault" : true,
      "id" : "4000000015189",
      "type" : "PORTAL"
    }, {
      "profileName" : "Supervisor",
      "isDefault" : false,
      "id" : "4000000015192",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Support Manager",
      "isDefault" : false,
      "id" : "4000000015195",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Newbie Agent",
      "isDefault" : false,
      "id" : "4000000015198",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Light Agent",
      "isDefault" : true,
      "id" : "4000000015201",
      "type" : "LIGHT"
    } ],
    "createdBy" : "4000000015894",
    "createdTime" : "2019-05-06T01:45:58.000Z",
    "modifiedBy" : "4000000015894",
    "id" : "4000000017001",
    "status" : "active"
  } ]
}

Get Layout

This API fetches a layout configured for a module

GET /api/v1/layouts/{layout_id}

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007177
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-07-01T07:36:04.000Z",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "layoutDisplayName" : "Default Ticket Layout",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "apiName" : "category",
      "isCustomField" : false,
      "defaultValue" : "General",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000421",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "apiName" : "status",
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000407",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutDesc" : "Default Layout of the Ticket",
  "layoutName" : "Default Ticket Layout"
}

Clone Layout

This API creates new Layout by cloning existing layout.

Attributes

Param Name

Data Type

Description

layoutName

string

required,
max chars : 150

Name of the layout

layoutDesc

string

optional,
max chars : 500

Description of the layout

layoutDisplayName

string

required,
max chars : 150

Display Name of the layout in HelpCenter

isDefaultLayout

boolean

required

Key that returns if the layout is the default layout in the module

POST /api/v1/layouts/{layout_id}/clone

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000013462/clone
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "skipDeptAccessValidation" : false, "layoutDisplayName" : "Clonned Account Layout", "layoutDesc" : "Layout of the accounts", "layoutName" : "cloneAccLayout1" }'

Response Example

{
  "modifiedTime" : "2019-05-08T02:21:34.000Z",
  "module" : "Accounts",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "layout of the accounts",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Account Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountName",
      "id" : "4000000000404",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 200,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000408",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000406",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Website",
      "isCustomField" : false,
      "name" : "website",
      "id" : "4000000000410",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "URL",
      "maxLength" : 2083,
      "isMandatory" : false
    }, {
      "displayLabel" : "Country",
      "isCustomField" : false,
      "name" : "country",
      "id" : "4000000000438",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Text",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Account Owner",
      "isCustomField" : false,
      "name" : "ownerId",
      "id" : "4000000000412",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "cloneAccLayout1",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-08T02:21:34.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000039001",
  "status" : "active"
}

Create Layout

This API creates the layout

Attributes

Param Name

Data Type

Description

isDefaultLayout

boolean

required

Key that returns if the layout is the default layout in the module

sections

list

required

sections in the layout

module

string

required,
max chars : 100

mdoule name

POST /api/v1/layouts

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "skipDeptAccessValidation" : false,
  "module" : "accounts",
  "departmentId" : "4000000012710",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "DESC",
  "sections" : [ {
    "name" : "Account Information",
    "i18NLabel" : "Account Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "id" : "4000000000404",
      "isMandatory" : true
    }, {
      "id" : "4000000000408",
      "isMandatory" : false
    }, {
      "id" : "4000000000406",
      "isMandatory" : false
    }, {
      "id" : "4000000000410",
      "isMandatory" : false
    }, {
      "id" : "4000000000438",
      "isMandatory" : false
    }, {
      "id" : "4000000000412",
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "accounts layout "
}'

Response Example

{
  "modifiedTime" : "2019-05-09T04:52:57.000Z",
  "departmentId" : "4000000012710",
  "module" : "Accounts",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "DESC",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Account Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountName",
      "id" : "4000000000404",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 200,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000408",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000406",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Website",
      "isCustomField" : false,
      "name" : "website",
      "id" : "4000000000410",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "URL",
      "maxLength" : 2083,
      "isMandatory" : false
    }, {
      "displayLabel" : "Country",
      "isCustomField" : false,
      "name" : "country",
      "id" : "4000000000438",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Text",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Account Owner",
      "isCustomField" : false,
      "name" : "ownerId",
      "id" : "4000000000412",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "accounts layout ",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-09T04:52:57.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000043004",
  "status" : "active"
}

Update Layout

This API updates details of an existing layout.

Attributes

Param Name

Data Type

Description

isDefaultLayout

boolean

optional

Key that returns if the layout is the default layout in the module

sections

list

optional

sections in the layout

module

string

optional,
max chars : 100

mdoule name

PATCH /api/v1/layouts/{layout_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007177
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "skipDeptAccessValidation" : false,
  "layoutDisplayName" : "ClonedLayout",
  "layoutDesc" : "Layout cloned from default layout",
  "sections" : [ {
    "name" : "Ticket Information",
    "i18NLabel" : "Ticket Information",
    "id" : 1,
    "fields" : [ {
      "id" : "4000000000353",
      "isMandatory" : true
    }, {
      "id" : "4000000000357",
      "isMandatory" : true
    }, {
      "id" : "4000000000355",
      "isMandatory" : false
    }, {
      "id" : "4000000000359",
      "isMandatory" : false
    }, {
      "id" : "4000000000361",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "General", "Defects" ],
      "id" : "4000000000421",
      "isMandatory" : false
    }, {
      "id" : "4000000000363",
      "isMandatory" : true
    }, {
      "id" : "4000000000365",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "defaultValue" : "Open",
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isMandatory" : true
    }, {
      "id" : "4000000000371",
      "isMandatory" : false
    }, {
      "id" : "4000000000369",
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "i18NLabel" : "Additional Information",
    "id" : 2,
    "fields" : [ {
      "id" : "4000000000405",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "defaultValue" : "-None-",
      "id" : "4000000000407",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "defaultValue" : "Phone",
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isMandatory" : false
    }, {
      "id" : "4000000000411",
      "isMandatory" : false
    }, {
      "id" : "4000000000413",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "defaultValue" : "-None-",
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isMandatory" : false
    }, {
      "id" : "4000000000417",
      "isMandatory" : false
    }, {
      "id" : "4000000000447",
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "ClonedLayout"
}'

Response Example

{
  "modifiedTime" : "2017-07-01T07:36:04.000Z",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "layoutDisplayName" : "ClonedLayout",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "apiName" : "category",
      "isCustomField" : false,
      "defaultValue" : "General",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000421",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "apiName" : "status",
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000407",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutDesc" : "Layout cloned from default layout",
  "layoutName" : "Default Ticket Layout"
}

Delete Layout

This API deletes a layout

Attributes

Param Name

Data Type

Description

transferToLayoutId

long

required

The layout id to which the entities in the deleted layout to be transferred to

DELETE /api/v1/layouts/{layout_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000038053
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "transferToLayoutId" : "4000000038039"
}'

Response Example

DeActivate Layout

This Api deactivates existing layout

Attributes

Param Name

Data Type

Description

transferToLayoutId

long

required

The layout id to which the entities in the deleted layout to be transferred to

POST /api/v1/layouts/{layout_id}/deactivate

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000038053/deactivate
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "transferToLayoutId" : "4000000038039"
}'

Response Example

Activate Layout

This api activates the deactivated Layout.

POST /api/v1/layouts/{layout_id}/activate

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000038053/activate
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2019-05-09T09:42:28.000Z",
  "departmentId" : "4000000012710",
  "module" : "Cases",
  "layoutDisplayName" : "ClonedLayout",
  "layoutDesc" : "DESC",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Case Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "isCustomField" : false,
      "name" : "departmentId",
      "id" : "4000000000556",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "isCustomField" : false,
      "name" : "contactId",
      "id" : "4000000000560",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountId",
      "id" : "4000000000558",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000562",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000564",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "isCustomField" : false,
      "name" : "subject",
      "id" : "4000000000566",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "isCustomField" : false,
      "name" : "description",
      "id" : "4000000000568",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000570",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Ticket Owner",
      "isCustomField" : false,
      "name" : "assigneeId",
      "id" : "4000000000574",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "isCustomField" : false,
      "name" : "productId",
      "id" : "4000000000572",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : true,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "isCustomField" : false,
      "name" : "dueDate",
      "id" : "4000000000610",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "priority",
      "sortBy" : "userDefined",
      "id" : "4000000000614",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Channel",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "name" : "channel",
      "sortBy" : "userDefined",
      "id" : "4000000000616",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "classification",
      "sortBy" : "userDefined",
      "id" : "4000000000622",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "isCustomField" : false,
      "name" : "resolution",
      "id" : "4000000000624",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "Tickets New Layout 6",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-06T05:30:06.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000038033",
  "status" : "active"
}

Get Layout Profiles

This api returns the profiles associated with a layout

GET /api/v1/layouts/{layout_id}/profiles

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000038033/profiles
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "profileName" : "Support Administrator",
    "isDefault" : true,
    "id" : "4000000015183",
    "type" : "ADMIN"
  }, {
    "profileName" : "Agent",
    "isDefault" : true,
    "id" : "4000000015186",
    "type" : "STANDARD"
  }, {
    "profileName" : "Help Center",
    "isDefault" : true,
    "id" : "4000000015189",
    "type" : "PORTAL"
  }, {
    "profileName" : "Supervisor",
    "isDefault" : false,
    "id" : "4000000015192",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Support Manager",
    "isDefault" : false,
    "id" : "4000000015195",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Newbie Agent",
    "isDefault" : false,
    "id" : "4000000015198",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Light Agent",
    "isDefault" : true,
    "id" : "4000000015201",
    "type" : "LIGHT"
  } ]
}

Associate Layout profiles

This api Associates the given profiles to the layout

Attributes

Param Name

Data Type

Description

layoutProfileIds

list

optional

The profile id to which the layout needs to be associated to

PATCH /api/v1/layouts/{layout_id}/profiles

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000013464/profiles
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "layoutProfileIds" : [ 4000000015183, 4000000015186, 4000000015189 ]
}'

Response Example

Standard Layout Format

This Api provides the standrd layout format for the given module with organisations fields that can be used for create layout

Query Params

Param Name

Data Type

Description

module

String

required

Name of the module whose layouts must be fetched. Values allowed are tickets, contacts, accounts , calls , events, tasks, timeEntry, products, and contracts.

GET /api/v1/layouts/standardLayoutFormat

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/standardLayoutFormat?module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "Case Information",
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "isCustomField" : false,
      "name" : "departmentId",
      "id" : "4000000000556",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountId",
      "id" : "4000000000558",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Contact Name",
      "isCustomField" : false,
      "name" : "contactId",
      "id" : "4000000000560",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000562",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000564",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "isCustomField" : false,
      "name" : "subject",
      "id" : "4000000000566",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "isCustomField" : false,
      "name" : "description",
      "id" : "4000000000568",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000570",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Product Name",
      "isCustomField" : false,
      "name" : "productId",
      "id" : "4000000000572",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Ticket Owner",
      "isCustomField" : false,
      "name" : "assigneeId",
      "id" : "4000000000574",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "isCustomField" : false,
      "name" : "dueDate",
      "id" : "4000000000610",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "priority",
      "sortBy" : "userDefined",
      "id" : "4000000000614",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Channel",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "name" : "channel",
      "sortBy" : "userDefined",
      "id" : "4000000000616",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "classification",
      "sortBy" : "userDefined",
      "id" : "4000000000622",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "isCustomField" : false,
      "name" : "resolution",
      "id" : "4000000000624",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Category Information",
    "id" : 3,
    "fields" : [ ]
  }, {
    "name" : "Related List Section",
    "id" : 4,
    "fields" : [ ]
  } ]
}

Get MyForm

This API fetches details of a layout, based on the profile of the current user. Status mappings and dependency mappings are also included

Query Params

Param Name

Data Type

Description

layoutId

long

optional

ID of the layout

GET /api/v1/myForm

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myForm?layoutId=4000000007177
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

LayoutAPI layout = ZDesk.getLayoutAPIInstance(mailId);
Layout response = layout.getMyForm(layoutId );

Response Example

{
  "modifiedTime" : "2017-07-10T10:32:11.000Z",
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "4000000009118",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isEncryptedField" : false,
      "id" : "4000000000423",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects", "ManojKumar" ],
      "apiName" : "category",
      "isCustomField" : false,
      "isReadOnly" : false,
      "defaultValue" : "General",
      "isEncryptedField" : false,
      "id" : "4000000000421",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "Open_newDept", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed", "julyDeptClosed", "julyDeptClosed1" ],
      "apiName" : "status",
      "isCustomField" : false,
      "isReadOnly" : false,
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Open_newDept", "Escalated", "On Hold", "Closed", "Closed1", "julyDeptClosed", "julyDeptClosed1", "Open" ],
      "defaultValue" : "Open",
      "isEncryptedField" : false,
      "id" : "4000000000367",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isEncryptedField" : false,
      "id" : "4000000000407",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isEncryptedField" : false,
      "id" : "4000000000409",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isEncryptedField" : false,
      "id" : "4000000000415",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "Default Ticket Layout"
}

Replace value in PickList field

This API replaces an existing value in a PickList field with a new value

Attributes

Param Name

Data Type

Description

fieldId

long

required

field Id

oldValue

string

required,
max chars : 100

oldValue

newValue

string

required,
max chars : 100

newValue

POST /api/v1/layouts/{layout_id}/replaceValues

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007177/replaceValues
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "newValue" : "Sub Defects1235", "oldValue" : "Sub Defects", "fieldId" : "4000000000423" }'

Response Example

Update Layout Field

This API updates details of a field in the layout.

Query Params

Param Name

Data Type

Description

Attributes

Param Name

Data Type

Description

isMandatory

boolean

optional

Key that returns if a field is mandatory in a layout or not

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields and PickList fields

allowedValues

list

optional

Values allowed in a field. Applicable for PickList fields

sortBy

string

optional,
max chars : 100

Key that sorts values in a PickList field either alphabetically or by a user-defined order

PATCH /api/v1/layouts/{layout_id}/fields/{field_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007177/fields/21000000023005
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "allowedValues" : [ "option 1", "option 2", "option 3", "option 4" ], "defaultValue" : "option 3", "sortBy" : "userDefined", "isMandatory" : "true" }'

Response Example

{
  "displayLabel" : "Multiselect 1",
  "allowedValues" : [ "option 3", "option 4", "option 1", "option 2" ],
  "apiName" : "cf_multiselect_1",
  "isCustomField" : true,
  "defaultValue" : "option 3",
  "i18NLabel" : "Multiselect 1",
  "isSystemMandatory" : false,
  "type" : "Multiselect",
  "name" : "Multiselect 1",
  "sortBy" : "userDefined",
  "id" : "21000000023005",
  "isRemovable" : true,
  "maxLength" : 120,
  "isMandatory" : true
}

Remove Field in Layout

This API is to remove fields from a layout.

POST /api/v1/layouts/{layout_id}/fields/([0-9]+)/unassociate

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007177/fields/4000000000353/unassociate
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Clone Fields to other Layout

This API is to clone a field to other layouts.

Attributes

Param Name

Data Type

Description

layoutIds

list

optional

List of layout ids to which the field should be cloned.

POST /api/v1/layouts/{layout_id}/fields/([0-9]+)/cloneFieldsInLayout

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/layouts/4000000007177/fields/4000000000353/cloneFieldsInLayout
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "layoutIds" : [ "4000000007187", "4000000007197" ]
}'

Response Example

LayoutRules

Layout rules enable you to configure a page layout to respond to a user's input as a record is created or edited. Depending on how you set it up, the rule can set mandatory fields, show or hide fields, and show or hide sections.

ATTRIBUTES

Attribute Name

Data Type

Description

name

string

Name of the rule

description

string

A short description of the rule

fieldName

string

Name of the primary field to be used for creating the rule

displayLabel

string

Display Label of the primary field to be used for creating the rule

status

string

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

To execute the rule in help centre or not: true or false

fieldConditions

show Attributes

list

Conditions in the layout rule

Example

{ "fieldConditions" : [ { "name" : "condition 1", "pattern" : "(1and2)", "conditions" : [ { "condition" : "is", "fieldName" : "email", "value" : [ "raj@zohocorp.com" ] }, { "condition" : "is", "fieldName" : "phone", "value" : [ "9993292892" ] } ], "actions" : { "showSections" : [ "Additional Information" ], "showFields" : [ "subject" ], "setMandatoryFields" : [ "priority" ] } } ], "fieldName" : "phone", "executeInHelpCentre" : false, "name" : "Rule 1", "description" : "Rule 1 for layout", "id" : "4000000020001", "systemGenerated" : false, "layoutId" : "4000000007723", "status" : "active" }

Get Layout Rule

This API fetches a single rule from your help desk layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000020001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 1",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000020001",
  "status" : "active"
}

Get Layout Rules for department or layout

This API lists all the rules configured for a department/layout.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Get the rules of the department

layoutId

long

optional

Get the rules of the layout

module

String

optional

Name of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events

activeLayouts

Boolean

optional

Get the rules for active layouts

activeRules

Boolean

optional

Get the rules that are active in the layout

executeInHelpCentre

Boolean

optional

Get the rules that can be executed in help centre

from

integer

optional,
default : 0,
range : >=0

Index number, starting from which the rules must be fetched

limit

integer

required,
default : 50,
range : 1-50

Number of rules to be fetched. Default is 50

searchString

String

optional

Get the rules that have this search term

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/layoutRules

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layoutRules?layoutId=4000000007723&module=tickets&activeRules=true&from=0&limit=10&searchString=Rule
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldConditions" : [ {
      "name" : "condition 1",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "raj@zohocorp.com" ]
      }, {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9993292892" ]
      } ],
      "actions" : {
        "showSections" : [ "Additional Information" ],
        "showFields" : [ "subject" ],
        "setMandatoryFields" : [ "priority" ]
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "email",
    "description" : "Rule 1 for layout",
    "systemGenerated" : false,
    "layoutId" : "4000000007723",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "name" : "Rule 1",
    "createdTime" : "2018-09-14T01:07:22.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000020001",
    "status" : "active"
  }, {
    "fieldConditions" : [ {
      "name" : "condition 2",
      "pattern" : "(1or2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9993292892" ]
      }, {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "raj@zohocorp.com" ]
      } ],
      "actions" : {
        "showSections" : [ "Additional Information" ],
        "showFields" : [ "subject" ],
        "setMandatoryFields" : [ "priority" ]
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "phone",
    "description" : "Rule 2 for layout",
    "systemGenerated" : false,
    "layoutId" : "4000000007723",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "name" : "Rule 2",
    "createdTime" : "2018-09-14T01:07:22.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000021001",
    "status" : "active"
  } ]
}

Create Layout Rule

This API creates a rule for a field in a layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 255

Name of the rule

description

string

optional,
max chars : 255

A short description of the rule

fieldName

string

required,
max chars : 100

Name of the primary field to be used for creating the rule

displayLabel

string

optional,
max chars : 100

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

required

Conditions in the layout rule

POST /api/v1/layouts/{layout_id}/layoutRules

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : true,
  "name" : "Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 2 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : true,
  "createdBy" : "4000000015963",
  "name" : "Rule 2",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Update Layout Rule

This API updates the details of an existing layout rule in a particular layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

Attributes

Param Name

Data Type

Description

name

string

optional,
max chars : 255

Name of the rule

description

string

optional,
max chars : 255

A short description of the rule

fieldName

string

optional,
max chars : 100

Name of the primary field to be used for creating the rule

displayLabel

string

optional,
max chars : 100

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

optional

Conditions in the layout rule

PATCH /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000021001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)or3",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Ramkumar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Honda" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  }, {
    "name" : "condition 2",
    "pattern" : "1 and (2 or 3)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Sundar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Maruthi" ]
    } ],
    "actions" : {
      "showSections" : [ ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "Description" ]
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "name" : "Rule 11",
  "description" : "Rule 1 for layout",
  "layoutId" : "4000000007723",
  "status" : "active"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)or3",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Ramkumar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Honda" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  }, {
    "name" : "condition 2",
    "pattern" : "1 and (2 or 3)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Sundar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Maruthi" ]
    } ],
    "actions" : {
      "showSections" : [ ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "Description" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 11",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Delete Layout Rule

This API deletes a layout rule created for a field from a layout.

DELETE /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000021001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List Criteria Fields For Layout Rules

This API lists the fields that can be used in criteria of a specified module in layout rules. Available pre-defined values may contain ${EMPTY}, ${NOTEMPTY}, ${OPEN}, ${CLOSED}, ${CURRENTTIME}. Available types are Text, Date, DateTime, Text, Boolean and Arithmetic.

Query Params

Param Name

Data Type

Description

category

String

required

Category for getting the field criteria for primary or secondary fields

GET /api/v1/layouts/{layout_id}/layoutRules/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000013564/layoutRules/criteriaFields?category=primary
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "accountId",
      "fieldLabel" : "Account Name",
      "i18NLabel" : "Account Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "contactId",
      "fieldLabel" : "Contact Name",
      "i18NLabel" : "Contact Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "phone",
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "status",
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "productId",
      "fieldLabel" : "Product Name",
      "i18NLabel" : "Product Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "dueDate",
      "fieldLabel" : "Due Date",
      "i18NLabel" : "Due Date",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "priority",
      "fieldLabel" : "Priority",
      "i18NLabel" : "Priority",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "channel",
      "fieldLabel" : "Mode",
      "i18NLabel" : "Mode",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "classification",
      "fieldLabel" : "Classification",
      "i18NLabel" : "Classification",
      "type" : "text"
    } ]
  } ]
}

ValidationRules

Validation rules verify that the data an agent enters in a record meets the standards you specify before the agent can save the record.

ATTRIBUTES

Attribute Name

Data Type

Description

fieldName

string

Name of the primary field to be used for creating the validation rule

displayLabel

string

Display Label of the primary field to be used for creating the rule

status

string

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

To execute the rule in help centre or not: true or false

fieldConditions

show Attributes

list

Conditions in the validation rule

Example

{ "fieldConditions" : [ { "name" : "condition 1", "pattern" : "(1and2)", "conditions" : [ { "condition" : "is", "fieldName" : "phone", "value" : [ "9994259718" ] }, { "condition" : "is", "fieldName" : "email", "value" : [ "raj@zoho.com" ] } ], "actions" : { "alert" : "Sample Alert" } } ], "fieldName" : "phone", "executeInHelpCentre" : true, "name" : "Validation Rule 1", "description" : "Validation Rule 1 for layout", "id" : "4000000020001", "systemGenerated" : false, "layoutId" : "4000000007723", "status" : "active" }

Get Layout Validation Rule

This API fetches a validation rule configured for your layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

GET /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000018001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zoho.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994259718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000018001",
  "systemGenerated" : false,
  "layoutId" : "4000000013564",
  "status" : "active"
}

Get Layout Validation Rules for department or layout

This API fetches all the validation rules configured for your department/layout.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Get the rules of the department

layoutId

long

optional

Get the rules of the layout

module

String

optional

Name of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events

activeLayouts

Boolean

optional

Get the rules for active layouts

activeRules

Boolean

optional

Get the rules that are active in the layout

from

integer

optional,
default : 0,
range : >=0

Index number, starting from which the rules must be fetched

limit

integer

required,
default : 50,
range : 1-50

Number of rules to be fetched. Default is 50

searchString

String

optional

Get the rules that have this search term

executeInHelpCentre

Boolean

optional

Get the rules that can be executed in help centre

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/validationRules

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/validationRules?layoutId=4000000007723&module=tickets&activeRules=true&from=0&limit=10&searchString=Rule
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldConditions" : [ {
      "name" : "condition 2",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "ramkumarmj@zohocorp.com" ]
      }, {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9994259718" ]
      } ],
      "actions" : {
        "alert" : "Sample Alert"
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "email",
    "executeInHelpCentre" : true,
    "createdBy" : "4000000015963",
    "createdTime" : "2018-09-13T01:16:46.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000017001",
    "systemGenerated" : false,
    "layoutId" : "4000000013564"
  }, {
    "fieldConditions" : [ {
      "name" : "condition 1",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9994259718" ]
      }, {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "ramkumarmj@zohocorp.com" ]
      } ],
      "actions" : {
        "alert" : "Sample Alert"
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "phone",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "createdTime" : "2018-09-13T01:49:03.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000018001",
    "systemGenerated" : false,
    "layoutId" : "4000000013564",
    "status" : "active"
  } ]
}

Create Layout Validation Rule

This API creates a validation rule for a field in a layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

Attributes

Param Name

Data Type

Description

fieldName

string

required,
max chars : 100

Name of the primary field to be used for creating the validation rule

displayLabel

string

optional,
max chars : 100

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

required

Conditions in the validation rule

POST /api/v1/layouts/layout_id/validationRules

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "executeInHelpCentre" : true,
  "fieldName" : "email",
  "name" : "Validation Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "modifiedTime" : "2018-09-07T06:50:48.697Z",
  "fieldName" : "email",
  "executeInHelpCentre" : true,
  "createdBy" : "4000000015963",
  "createdTime" : "2018-09-07T06:50:48.697Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000018001",
  "systemGenerated" : false,
  "layoutId" : "4000000013564",
  "status" : "active"
}

Update Layout Validation Rule

This API updates the details of an existing validation rule in a particular layout.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

Attributes

Param Name

Data Type

Description

fieldName

string

optional,
max chars : 100

Name of the primary field to be used for creating the validation rule

displayLabel

string

optional,
max chars : 100

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

optional

Conditions in the validation rule

PATCH /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000021001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  }, {
    "name" : "condition 3",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "99922299922" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert1"
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "name" : "Validation Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  }, {
    "name" : "condition 3",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raja@zohocorp.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "99922299922" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert1"
    }
  } ],
  "modifiedTime" : "2018-09-07T06:50:48.697Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 11",
  "createdTime" : "2018-09-07T06:50:48.697Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Delete Validation Rule

This API deletes a validation rule created for a field from a layout.

DELETE /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000021001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List Criteria Fields For Layout Validation Rules

This API lists the fields that can be used in criteria of a specified module in validation rules. Available pre-defined values may contain ${EMPTY}, ${NOTEMPTY}, ${OPEN}, ${CLOSED}, ${CURRENTTIME}. Available types are Text, Date, DateTime, Text, Boolean and Arithmetic.

Query Params

Param Name

Data Type

Description

category

String

required

Category for getting the field criteria for primary or secondary fields

GET /api/v1/layouts/{layout_id}/validationRules/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000013564/validationRules/criteriaFields?category=primary
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "email",
      "fieldLabel" : "Email",
      "i18NLabel" : "Email",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "phone",
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "subject",
      "fieldLabel" : "Subject",
      "i18NLabel" : "Subject",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "status",
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "classification",
      "fieldLabel" : "Classification",
      "i18NLabel" : "Classification",
      "type" : "text"
    } ]
  } ]
}

DependencyMappings

Dependency mapping is a function that is applicable only to PickList fields. Through this function, you can define a parent-child relationship between two fields. For example, let's say there are two fields - Country and State - in your Tickets module. The State field will display values, depending on the value you select in the Country field. If you choose India in the Country field, only the states of India will be displayed in the State field and the states of other countries will be hidden. If you choose a different country, only the states of that country will be displayed.

ATTRIBUTES

Attribute Name

Data Type

Description

layoutId

long

ID of the layout in which the dependency is mapped

parentId

long

ID of the parent field

childId

long

ID of the child field

mappings

list

JSON object that shows the mapping configured

Example

{ "parent" : { "displayLabel" : "Category", "allowedValues" : [ "General", "Defects" ], "id" : "4000000000421" }, "mappings" : { "General" : [ "Sub General" ], "Defects" : [ "Sub Defects" ] }, "id" : "4000000007315", "childId" : "4000000000423", "layoutId" : "4000000007177", "parentId" : "4000000000421", "child" : { "displayLabel" : "Sub Category", "allowedValues" : [ "Sub General", "Sub Defects" ], "id" : "4000000000423" } }

List dependency mappings in a layout

This API lists the dependency mappings configured in a layout.

Query Params

Param Name

Data Type

Description

layoutId

long

optional

ID of the layout in which the dependency is mapped

GET /api/v1/dependencyMappings

OAuth Scope

Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/dependencyMappings?layoutId=4000000007177
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "parent" : {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "id" : "4000000000421"
    },
    "mappings" : {
      "General" : [ "Sub General" ],
      "Defects" : [ "Sub Defects" ]
    },
    "id" : "4000000007315",
    "childId" : "4000000000423",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000421",
    "child" : {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "id" : "4000000000423"
    }
  }, {
    "parent" : {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "id" : "4000000000421"
    },
    "mappings" : {
      "General" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "Defects" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ]
    },
    "id" : "4000000031003",
    "childId" : "4000000000367",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000421",
    "child" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "id" : "4000000000367"
    }
  }, {
    "parent" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "id" : "4000000000367"
    },
    "mappings" : {
      "newDeptClosed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open_july" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Escalated" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open_newDept" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "On Hold" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Closed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Closed1" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "julyDeptClosed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ]
    },
    "id" : "4000000032003",
    "childId" : "4000000000409",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000367",
    "child" : {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "id" : "4000000000409"
    }
  } ]
}

Get possible dependency mappings in a layout

This API fetches the parent and child fields using which you can configure dependency mappings in a layout.

Query Params

Param Name

Data Type

Description

layoutId

long

required

layout Id

GET /api/v1/availableDependencyMappings

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/availableDependencyMappings?layoutId=4000000007179
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "children" : [ {
    "displayLabel" : "Category",
    "allowedValues" : [ "-None-", "Call", "Meeting", "Demo" ],
    "id" : "4000000000145"
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ "Not Started", "Deferred", "In Progress", "Waiting on someone else", "Completed_july1", "Completed_newDept" ],
    "id" : "4000000000147"
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Highest", "Low", "Lowest", "Normal" ],
    "id" : "4000000000149"
  } ],
  "parents" : [ {
    "displayLabel" : "Category",
    "allowedValues" : [ "-None-", "Call", "Meeting", "Demo" ],
    "id" : "4000000000145"
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ "Not Started", "Deferred", "In Progress", "Waiting on someone else", "Completed_july1", "Completed_newDept" ],
    "id" : "4000000000147"
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Highest", "Low", "Lowest", "Normal" ],
    "id" : "4000000000149"
  } ]
}

Create dependency mapping

This API creates a dependency mapping between two fields.

Attributes

Param Name

Data Type

Description

layoutId

long

required

ID of the layout in which the dependency is mapped

parentId

long

required

ID of the parent field

childId

long

required

ID of the child field

mappings

list

required

JSON object that shows the mapping configured

POST /api/v1/dependencyMappings

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/dependencyMappings
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "mappings" : {
    "General" : [ "Medium", "High" ],
    "Defects" : [ "Low" ]
  },
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421"
}'

Response Example

{
  "parent" : {
    "displayLabel" : "Category",
    "allowedValues" : [ "General", "Defects" ],
    "id" : "4000000000421"
  },
  "mappings" : {
    "General" : [ "High", "Medium" ],
    "Defects" : [ "Low" ]
  },
  "id" : "4000000047001",
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421",
  "child" : {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Medium", "Low" ],
    "id" : "4000000000407"
  }
}

Update dependency mapping

This API updates details of an existing dependency mapping.

Attributes

Param Name

Data Type

Description

mappings

list

optional

a Json object which consist of elements which are inturn a json array

PATCH /api/v1/dependencyMappings/{dependencymapping_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/dependencyMappings/4000000047001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "mappings" : {
    "General" : [ "Medium", "Low" ],
    "Defects" : [ "Low", "Medium" ]
  }
}'

Response Example

{
  "parent" : {
    "displayLabel" : "Category",
    "allowedValues" : [ "General", "Defects" ],
    "id" : "4000000000421"
  },
  "mappings" : {
    "General" : [ "Medium", "Low" ],
    "Defects" : [ "Medium", "Low" ]
  },
  "id" : "4000000047001",
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421",
  "child" : {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Medium", "Low" ],
    "id" : "4000000000407"
  }
}

Delete dependency mapping

This API deletes a dependency mapping from a layout.

DELETE /api/v1/dependencyMappings/{dependencymapping_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/dependencyMappings/4000000047001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

MailReplyAddress

MailReplyAddress refers to the email ID from which replies are sent to customers.

Example

{ "address" : "techsupport@zylker.com", "smtpDetails" : { "password" : "lfijkrffr", "port" : "465", "host" : "smtp.zoho.com", "userName" : "techsupport@zylker.com", "connectionType" : "SSL" }, "isVerified" : true, "isSmtpEnabled" : true, "displayName" : "Tech", "departmentId" : "4000000007043", "id" : "4000000028003", "isActive" : true }

Get details of a MailReplyAddress

This API fetches the details of a MailReplyAddress.

GET /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress/4000000028003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "address" : "techsupport@zylker.com",
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "userName" : "techsupport@zylker.com",
    "connectionType" : "SSL"
  },
  "isVerified" : true,
  "isSmtpEnabled" : true,
  "displayName" : "Tech",
  "departmentId" : "4000000007043",
  "id" : "4000000028003",
  "isActive" : true
}

List MailReplyAddresses

This API lists the mailReplyAddresses configured in your help desk portal.

Query Params

Param Name

Data Type

Description

departmentId

long

required

ID of the Department from which the addresses need to be queried.

isActive

boolean

optional

Key that returns if the mailReplyAddress is active or not

from

integer

optional

Index number, starting from which the mail addresses must be fetched

limit

integer

optional,
range : 1-100

Number of mail addresses to fetch

GET /api/v1/mailReplyAddress

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress?departmentId=4000000007043
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

MailReplyAddressAPI mailReplyAddress = ZDesk.getMailReplyAddressAPIInstance(mailId);
GetReplyMailAddressesFilter filter = new GetReplyMailAddressesFilter.Builder().setDepartmentId(departmentId).build();
List<MailReplyAddress> response = mailReplyAddress.getReplyMailAddresses( from, limit, filter );

Response Example

{
  "data" : [ {
    "address" : "support@zylker.com",
    "smtpDetails" : {
      "port" : "465",
      "host" : "smtp.zoho.com",
      "userName" : "support@zylker.com",
      "connectionType" : "SSL"
    },
    "isVerified" : true,
    "isSmtpEnabled" : true,
    "displayName" : "Support",
    "departmentId" : "4000000007043",
    "id" : "4000000025003",
    "isActive" : true
  }, {
    "address" : "market@zylker.com",
    "isVerified" : true,
    "isSmtpEnabled" : false,
    "displayName" : "Marketing",
    "departmentId" : "4000000007043",
    "id" : "4000000026001",
    "isActive" : false
  }, {
    "address" : "techsupport@zylker.com",
    "smtpDetails" : {
      "port" : "465",
      "host" : "smtp.zoho.com",
      "userName" : "techsupport@zylker.com",
      "connectionType" : "SSL"
    },
    "isVerified" : true,
    "isSmtpEnabled" : true,
    "displayName" : "Tech",
    "departmentId" : "4000000007043",
    "id" : "4000000028003",
    "isActive" : true
  } ]
}

Add MailReplyAddress

This API adds a MailReplyAddress to your help desk.

Attributes

Param Name

Data Type

Description

departmentId

long

required

ID of the department in which the MailReplyAddress must be configured

address

string

required,
max chars : 100

Email ID to add

displayName

string

required,
max chars : 100

Display name for the MailReplyAddress

isSmtpEnabled

boolean

required

Key that enables or disables SMTP authentication for the MailReplyAddress

smtpDetails

JSONObject

optional

Details related to the SMTP authentication for the MailReplyAddress

POST /api/v1/mailReplyAddress

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/mailReplyAddress
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "address" : "support@zylker.com", "smtpDetails" : { "port" : "465", "host" : "smtp.zoho.com", "password " : "lfijkrffr", "userName" : "support@zylker.com", "connectionType" : "SSL" }, "isSmtpEnabled" : true, "displayName" : "My address", "departmentId" : "4000000007043" }'

Response Example

{
  "address" : "support@zylker.com",
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "userName" : "support@zylker.com",
    "connectionType" : "SSL"
  },
  "isVerified" : false,
  "displayName" : "My address",
  "departmentId" : "4000000007043",
  "id" : "4000000028003",
  "isActive" : true
}

Update MailReplyAddress

This API updates details of an existing MailReplyAddress.

Attributes

Param Name

Data Type

Description

departmentId

long

optional

ID of the department(s) in which the MailReplyAddress is configured

displayName

string

optional,
max chars : 100

Display Name

isActive

boolean

optional

Key that returns if the MailReplyAddress is active or not

isSmtpEnabled

boolean

optional

Is SMTP Enabled

smtpDetails

JSONObject

optional

Details related to the SMTP authentication for the MailReplyAddress

PATCH /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "smtpDetails" : { "port" : "465", "host" : "smtp.zoho.com", "password " : "lfijk$&rffr**", "userName" : "techsupport@zylker.com", "connectionType" : "SSL" }, "isSmtpEnabled" : true, "displayName" : "TechSupport", "departmentId" : "4000000007043", "isActive" : true }'

Response Example

{
  "address" : "techsupport@zylker.com",
  "isVerified" : true,
  "displayName" : "TechSupport",
  "departmentId" : "4000000007043",
  "id" : "4000000028003",
  "isActive" : true
}

Delete MailReplyAddress

This API deletes a MailReplyAddress from your help desk.

DELETE /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Verify MailReplyAddress

This API sends a verification link to the MailReplyAddress configured in your help desk portal.

POST /api/v1/mailReplyAddress/{mailReplyAddress_id}/sendVerification

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003/sendVerification
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

SupportEmailAddress

SupportEmailAddress refers to the email ID to which customer correspondences are forwarded.

Example

{ "address" : "support@zylker.zohodesk.com", "departmentId" : "4000000007043", "id" : "4000000026003", "friendlyName" : "Tech", "isMailFetching" : true }

Get details of a SupportEmailAddress

This API fetches the details of a SupportEmailAddress.

GET /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailAddress/4000000026003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "address" : "support@zylker.zohodesk.com",
  "departmentId" : "4000000007043",
  "id" : "4000000026003",
  "friendlyName" : "Tech",
  "isMailFetching" : true
}

List SupportEmailAddresses

This API lists the SupportEmailAddresses configured in your help desk.

Query Params

Param Name

Data Type

Description

departmentId

long

required

ID of the department(s) from which the SupportEmailAddresses must be fetched.

from

integer

optional

Index number, starting from which the mail addresses must be fetched

limit

integer

optional,
range : 1-100

Number of mail addresses to fetch

GET /api/v1/supportEmailAddress

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailAddress?departmentId=4000000007043
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "address" : "marketing@zylker.zohodesk.com",
    "departmentId" : "4000000007043",
    "id" : "4000000025003",
    "friendlyName" : "Marketing",
    "isMailFetching" : true
  }, {
    "address" : "sales@zylker.zohodesk.com",
    "departmentId" : "4000000007043",
    "id" : "4000000026001",
    "friendlyName" : "Sales",
    "isMailFetching" : false
  }, {
    "address" : "support@zylker.zohodesk.com",
    "departmentId" : "4000000007043",
    "id" : "4000000026003",
    "friendlyName" : "Support",
    "isMailFetching" : true
  } ]
}

Add SupportEmailAddress

This API adds a SupportEmailAddress to your help desk.

Attributes

Param Name

Data Type

Description

departmentId

long

required

ID of the department in which the SupportEmailAddress must be configured

friendlyName

string

required,
max chars : 100

Display name for the SupportEmailAddress

address

string

required,
max chars : 100

Email ID to add

POST /api/v1/supportEmailAddress

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/supportEmailAddress
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "address" : "support@zylker.zohodesk.com", "departmentId" : "4000000007043", "friendlyName" : "Support" }'

Response Example

{
  "address" : "support@zylker.zohodesk.com",
  "departmentId" : "4000000007043",
  "id" : "4000000026003",
  "friendlyName" : "Support",
  "isMailFetching" : true
}

Update SupportEmailAddress

This API updates details of an existing SupportEmailAddress.

Attributes

Param Name

Data Type

Description

departmentId

long

optional

ID of the department in which the SupportEmailAddress is configured

friendlyName

string

optional,
max chars : 100

Display name for the SupportEmailAddress

isMailFetching

boolean

optional

Key that returns if the SupportEmailAddress fetches emails or not

PATCH /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/supportEmailAddress/4000000039003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "departmentId" : "4000000007043", "friendlyName" : "TechSupport", "isMailFetching" : true }'

Response Example

{
  "address" : "support@zylker.zohodesk.com",
  "departmentId" : "4000000007043",
  "id" : "4000000026003",
  "friendlyName" : "TechSupport",
  "isMailFetching" : true
}

Delete SupportEmailAddress

This API deletes a SupportEmailAddress from your help desk.

DELETE /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/supportEmailAddress/4000000039003
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

MailConfigurations

MailConfiguration refers to the secondary configurations related to the email addresses in your help desk portal.

Example

{ "privateThreadConfig" : true, "agentNameInTicketReply" : true, "createContactWithReplyTo" : false, "createTicketForOriginalSender" : true, "autoCCToMailbox" : true }

List department-level MailConfigurations

This API lists the MailConfigurations set for a specific department.

GET /api/v1/departments/{department_Id}/mailConfigurations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/4000000007043/mailConfigurations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

List organization-level MailConfigurations

This API lists the MailConfigurations set for the entire help desk portal.

GET /api/v1/mailConfigurations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/mailConfigurations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

Update department-level MailConfigurations

This API updates the MailConfigurations set for a specific department.

Attributes

Param Name

Data Type

Description

autoCCToMailbox

boolean

optional

Key that enables or disables auto CC of email replies to your

createContactWithReplyTo

boolean

optional

Key that enables or disables creation of contacts from 'Reply To' email addresses

agentNameInTicketReply

boolean

optional

Key that enables or disables display of the agent's name in replies to customers

createTicketForOriginalSender

boolean

optional

Key that enables or disables creation of tickets on behalf of the sender while forwarding emails

privateThreadConfig

boolean

optional

Key that enables or disables private thread handling

PATCH /api/v1/departments/{department_Id}/mailConfigurations

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/departments/4000000007043/mailConfigurations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "agentNameInTicketReply" : true, "createContactWithReplyTo" : false, "createTicketForOriginalSender" : true, "autoCCToMailbox" : true }'

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

Update organization-level MailConfigurations

This API updates the MailConfigurations set for the entire help desk portal.

Attributes

Param Name

Data Type

Description

autoCCToMailbox

boolean

optional

Key that enables or disables auto CC of email replies to your

createContactWithReplyTo

boolean

optional

Key that enables or disables creation of contacts from 'Reply To' email addresses

agentNameInTicketReply

boolean

optional

Key that enables or disables display of the agent's name in replies to customers

createTicketForOriginalSender

boolean

optional

Key that enables or disables creation of tickets on behalf of the sender while forwarding emails

privateThreadConfig

boolean

optional

Key that enables or disables private thread handling

PATCH /api/v1/mailConfigurations

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/mailConfigurations
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "privateThreadConfig" : true, "agentNameInTicketReply" : true, "createContactWithReplyTo" : false, "createTicketForOriginalSender" : true, "autoCCToMailbox" : true }'

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

SupportEmailDomain

When you sign up for Zoho Desk, you are provided with one default support email address: support@mycompany.zohodesk.com. The "mycompany" part of the email address represents the portal name that you initially signed up with.Emails received at this address become tickets. This address is also used as the "From" address in replies to users.

Example

{ "updatedTime" : "2013-11-04T11:21:07.000Z", "updatedBy" : "4000000007089", "supportEmailDomain" : "zylker.zohodesk.com", "oldDomain" : "zylkernew.zohodesk.com" }

Update SupportEmailAddress SubDomain

This API updates the subdomain (the "mycompany" part) of the support email address.

1. Only the primary contact of the organization can update the subdomain of the support email address.
2. The new support email address will be support@newdomain.zohodesk.com.
3. The updated support email address will be used for fetching emails, henceforth. So make sure that you update the new address in the forwarding configurations of your mailbox.
4. The new support email address is applicable only for the default department.
5. All existing email aliases along with the old support email address will be permanently deleted from your account.
6. Emails forwarded to the old support address will not be fetched in.

Attributes

Param Name

Data Type

Description

supportEmailDomain

string

optional,
max chars : 100

Name of the new email subdomain

PATCH /api/v1/supportEmailDomain

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/supportEmailDomain
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "supportEmailDomain" : "zylkernew"
}'

Response Example

{
  "updatedTime" : "2013-11-04T11:21:07.000Z",
  "updatedBy" : "4000000007089",
  "supportEmailDomain" : "zylkernew.zohodesk.com",
  "oldDomain" : "zylker.zohodesk.com"
}

Get SupportEmailAddress SubDomain

This API fetches the subdomain of the support email address.

GET /api/v1/supportEmailDomain

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailDomain
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "updatedTime" : "2013-11-04T11:21:07.000Z",
  "updatedBy" : "4000000007089",
  "supportEmailDomain" : "zylkernew.zohodesk.com",
  "oldDomain" : "zylker.zohodesk.com"
}

Locales

These public APIs help access details of the countries,languages and time zones supported in Zoho Desk.

Example

{ "languages" : { "English (United States)" : "en_US", "Japanese" : "ja_JP" }, "countries" : { "Albanian" : "sq_AL", "Afghanistan" : "ps_AF" } }

List all countries

This API lists the countries that can be set in the locale field in Zoho Desk. Keep in mind that the countries object will be deprecated soon. Therefore, make sure to use the data object instead, wherever needed.

GET /api/v1/countries

OAuth Scope

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/countries
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "Puerto Rico",
    "id" : "PR"
  }, {
    "name" : "Palestine",
    "id" : "PS"
  }, {
    "name" : "Portugal",
    "id" : "PT"
  }, {
    "name" : "Palau",
    "id" : "PW"
  }, {
    "name" : "Paraguay",
    "id" : "PY"
  }, {
    "name" : "Qatar",
    "id" : "QA"
  }, {
    "name" : "Andorra",
    "id" : "AD"
  }, {
    "name" : "United Arab Emirates",
    "id" : "AE"
  }, {
    "name" : "Afghanistan",
    "id" : "AF"
  }, {
    "name" : "Antigua and Barbuda",
    "id" : "AG"
  }, {
    "name" : "Anguilla",
    "id" : "AI"
  }, {
    "name" : "Albania",
    "id" : "AL"
  }, {
    "name" : "Armenia",
    "id" : "AM"
  }, {
    "name" : "Netherlands Antilles",
    "id" : "AN"
  }, {
    "name" : "Angola",
    "id" : "AO"
  }, {
    "name" : "Antarctica",
    "id" : "AQ"
  }, {
    "name" : "Argentina",
    "id" : "AR"
  }, {
    "name" : "American Samoa",
    "id" : "AS"
  }, {
    "name" : "Austria",
    "id" : "AT"
  }, {
    "name" : "Reunion",
    "id" : "RE"
  }, {
    "name" : "Australia",
    "id" : "AU"
  }, {
    "name" : "Aruba",
    "id" : "AW"
  }, {
    "name" : "Åland Islands",
    "id" : "AX"
  }, {
    "name" : "Azerbaijan",
    "id" : "AZ"
  }, {
    "name" : "Romania",
    "id" : "RO"
  }, {
    "name" : "Bosnia and Herzegovina",
    "id" : "BA"
  }, {
    "name" : "Barbados",
    "id" : "BB"
  }, {
    "name" : "Serbia",
    "id" : "RS"
  }, {
    "name" : "Bangladesh",
    "id" : "BD"
  }, {
    "name" : "Belgium",
    "id" : "BE"
  }, {
    "name" : "Russia",
    "id" : "RU"
  }, {
    "name" : "Burkina Faso",
    "id" : "BF"
  }, {
    "name" : "Bulgaria",
    "id" : "BG"
  }, {
    "name" : "Rwanda",
    "id" : "RW"
  }, {
    "name" : "Bahrain",
    "id" : "BH"
  }, {
    "name" : "Burundi",
    "id" : "BI"
  }, {
    "name" : "Benin",
    "id" : "BJ"
  }, {
    "name" : "Saint Barthélemy",
    "id" : "BL"
  }, {
    "name" : "Bermuda",
    "id" : "BM"
  }, {
    "name" : "Brunei",
    "id" : "BN"
  }, {
    "name" : "Bolivia",
    "id" : "BO"
  }, {
    "name" : "Saudi Arabia",
    "id" : "SA"
  }, {
    "name" : "Bonaire, Sint Eustatius and Saba",
    "id" : "BQ"
  }, {
    "name" : "Solomon Islands",
    "id" : "SB"
  }, {
    "name" : "Brazil",
    "id" : "BR"
  }, {
    "name" : "Seychelles",
    "id" : "SC"
  }, {
    "name" : "Bahamas",
    "id" : "BS"
  }, {
    "name" : "Sudan",
    "id" : "SD"
  }, {
    "name" : "Bhutan",
    "id" : "BT"
  }, {
    "name" : "Sweden",
    "id" : "SE"
  }, {
    "name" : "Bouvet Island",
    "id" : "BV"
  }, {
    "name" : "Singapore",
    "id" : "SG"
  }, {
    "name" : "Botswana",
    "id" : "BW"
  }, {
    "name" : "Saint Helena",
    "id" : "SH"
  }, {
    "name" : "Slovenia",
    "id" : "SI"
  }, {
    "name" : "Belarus",
    "id" : "BY"
  }, {
    "name" : "Svalbard And Jan Mayen",
    "id" : "SJ"
  }, {
    "name" : "Belize",
    "id" : "BZ"
  }, {
    "name" : "Slovakia",
    "id" : "SK"
  }, {
    "name" : "Sierra Leone",
    "id" : "SL"
  }, {
    "name" : "San Marino",
    "id" : "SM"
  }, {
    "name" : "Senegal",
    "id" : "SN"
  }, {
    "name" : "Somalia",
    "id" : "SO"
  }, {
    "name" : "Canada",
    "id" : "CA"
  }, {
    "name" : "Suriname",
    "id" : "SR"
  }, {
    "name" : "Cocos Islands",
    "id" : "CC"
  }, {
    "name" : "South Sudan",
    "id" : "SS"
  }, {
    "name" : "The Democratic Republic Of Congo",
    "id" : "CD"
  }, {
    "name" : "Sao Tome And Principe",
    "id" : "ST"
  }, {
    "name" : "Central African Republic",
    "id" : "CF"
  }, {
    "name" : "El Salvador",
    "id" : "SV"
  }, {
    "name" : "Congo",
    "id" : "CG"
  }, {
    "name" : "Switzerland",
    "id" : "CH"
  }, {
    "name" : "Sint Maarten (Dutch part)",
    "id" : "SX"
  }, {
    "name" : "Côte d'Ivoire",
    "id" : "CI"
  }, {
    "name" : "Syria",
    "id" : "SY"
  }, {
    "name" : "Swaziland",
    "id" : "SZ"
  }, {
    "name" : "Cook Islands",
    "id" : "CK"
  }, {
    "name" : "Chile",
    "id" : "CL"
  }, {
    "name" : "Cameroon",
    "id" : "CM"
  }, {
    "name" : "China",
    "id" : "CN"
  }, {
    "name" : "Colombia",
    "id" : "CO"
  }, {
    "name" : "Costa Rica",
    "id" : "CR"
  }, {
    "name" : "Turks And Caicos Islands",
    "id" : "TC"
  }, {
    "name" : "Chad",
    "id" : "TD"
  }, {
    "name" : "Cuba",
    "id" : "CU"
  }, {
    "name" : "French Southern Territories",
    "id" : "TF"
  }, {
    "name" : "Cape Verde",
    "id" : "CV"
  }, {
    "name" : "Togo",
    "id" : "TG"
  }, {
    "name" : "Curaçao",
    "id" : "CW"
  }, {
    "name" : "Thailand",
    "id" : "TH"
  }, {
    "name" : "Christmas Island",
    "id" : "CX"
  }, {
    "name" : "Cyprus",
    "id" : "CY"
  }, {
    "name" : "Tajikistan",
    "id" : "TJ"
  }, {
    "name" : "Czech Republic",
    "id" : "CZ"
  }, {
    "name" : "Tokelau",
    "id" : "TK"
  }, {
    "name" : "Timor-Leste",
    "id" : "TL"
  }, {
    "name" : "Turkmenistan",
    "id" : "TM"
  }, {
    "name" : "Tunisia",
    "id" : "TN"
  }, {
    "name" : "Tonga",
    "id" : "TO"
  }, {
    "name" : "Turkey",
    "id" : "TR"
  }, {
    "name" : "Trinidad and Tobago",
    "id" : "TT"
  }, {
    "name" : "Germany",
    "id" : "DE"
  }, {
    "name" : "Tuvalu",
    "id" : "TV"
  }, {
    "name" : "Taiwan",
    "id" : "TW"
  }, {
    "name" : "Djibouti",
    "id" : "DJ"
  }, {
    "name" : "Tanzania",
    "id" : "TZ"
  }, {
    "name" : "Denmark",
    "id" : "DK"
  }, {
    "name" : "Dominica",
    "id" : "DM"
  }, {
    "name" : "Dominican Republic",
    "id" : "DO"
  }, {
    "name" : "Ukraine",
    "id" : "UA"
  }, {
    "name" : "Uganda",
    "id" : "UG"
  }, {
    "name" : "Algeria",
    "id" : "DZ"
  }, {
    "name" : "United States Minor Outlying Islands",
    "id" : "UM"
  }, {
    "name" : "Ecuador",
    "id" : "EC"
  }, {
    "name" : "United States",
    "id" : "US"
  }, {
    "name" : "Estonia",
    "id" : "EE"
  }, {
    "name" : "Egypt",
    "id" : "EG"
  }, {
    "name" : "Western Sahara",
    "id" : "EH"
  }, {
    "name" : "Uruguay",
    "id" : "UY"
  }, {
    "name" : "Uzbekistan",
    "id" : "UZ"
  }, {
    "name" : "Vatican",
    "id" : "VA"
  }, {
    "name" : "Eritrea",
    "id" : "ER"
  }, {
    "name" : "Saint Vincent And The Grenadines",
    "id" : "VC"
  }, {
    "name" : "Spain",
    "id" : "ES"
  }, {
    "name" : "Ethiopia",
    "id" : "ET"
  }, {
    "name" : "Venezuela",
    "id" : "VE"
  }, {
    "name" : "British Virgin Islands",
    "id" : "VG"
  }, {
    "name" : "U.S. Virgin Islands",
    "id" : "VI"
  }, {
    "name" : "Vietnam",
    "id" : "VN"
  }, {
    "name" : "Vanuatu",
    "id" : "VU"
  }, {
    "name" : "Finland",
    "id" : "FI"
  }, {
    "name" : "Fiji",
    "id" : "FJ"
  }, {
    "name" : "Falkland Islands",
    "id" : "FK"
  }, {
    "name" : "Micronesia",
    "id" : "FM"
  }, {
    "name" : "Faroe Islands",
    "id" : "FO"
  }, {
    "name" : "France",
    "id" : "FR"
  }, {
    "name" : "Wallis And Futuna",
    "id" : "WF"
  }, {
    "name" : "Gabon",
    "id" : "GA"
  }, {
    "name" : "United Kingdom",
    "id" : "GB"
  }, {
    "name" : "Samoa",
    "id" : "WS"
  }, {
    "name" : "Grenada",
    "id" : "GD"
  }, {
    "name" : "Georgia",
    "id" : "GE"
  }, {
    "name" : "French Guiana",
    "id" : "GF"
  }, {
    "name" : "Guernsey",
    "id" : "GG"
  }, {
    "name" : "Ghana",
    "id" : "GH"
  }, {
    "name" : "Gibraltar",
    "id" : "GI"
  }, {
    "name" : "Greenland",
    "id" : "GL"
  }, {
    "name" : "Gambia",
    "id" : "GM"
  }, {
    "name" : "Guinea",
    "id" : "GN"
  }, {
    "name" : "Guadeloupe",
    "id" : "GP"
  }, {
    "name" : "Equatorial Guinea",
    "id" : "GQ"
  }, {
    "name" : "Greece",
    "id" : "GR"
  }, {
    "name" : "South Georgia And The South Sandwich Islands",
    "id" : "GS"
  }, {
    "name" : "Guatemala",
    "id" : "GT"
  }, {
    "name" : "Guam",
    "id" : "GU"
  }, {
    "name" : "Guinea-Bissau",
    "id" : "GW"
  }, {
    "name" : "Guyana",
    "id" : "GY"
  }, {
    "name" : "Kosovo",
    "id" : "XK"
  }, {
    "name" : "Hong Kong",
    "id" : "HK"
  }, {
    "name" : "Heard Island And McDonald Islands",
    "id" : "HM"
  }, {
    "name" : "Honduras",
    "id" : "HN"
  }, {
    "name" : "Croatia",
    "id" : "HR"
  }, {
    "name" : "Haiti",
    "id" : "HT"
  }, {
    "name" : "Yemen",
    "id" : "YE"
  }, {
    "name" : "Hungary",
    "id" : "HU"
  }, {
    "name" : "Indonesia",
    "id" : "ID"
  }, {
    "name" : "Mayotte",
    "id" : "YT"
  }, {
    "name" : "Ireland",
    "id" : "IE"
  }, {
    "name" : "Israel",
    "id" : "IL"
  }, {
    "name" : "Isle Of Man",
    "id" : "IM"
  }, {
    "name" : "India",
    "id" : "IN"
  }, {
    "name" : "British Indian Ocean Territory",
    "id" : "IO"
  }, {
    "name" : "South Africa",
    "id" : "ZA"
  }, {
    "name" : "Iraq",
    "id" : "IQ"
  }, {
    "name" : "Iran",
    "id" : "IR"
  }, {
    "name" : "Iceland",
    "id" : "IS"
  }, {
    "name" : "Italy",
    "id" : "IT"
  }, {
    "name" : "Zambia",
    "id" : "ZM"
  }, {
    "name" : "Jersey",
    "id" : "JE"
  }, {
    "name" : "Zimbabwe",
    "id" : "ZW"
  }, {
    "name" : "Jamaica",
    "id" : "JM"
  }, {
    "name" : "Jordan",
    "id" : "JO"
  }, {
    "name" : "Japan",
    "id" : "JP"
  }, {
    "name" : "Kenya",
    "id" : "KE"
  }, {
    "name" : "Kyrgyzstan",
    "id" : "KG"
  }, {
    "name" : "Cambodia",
    "id" : "KH"
  }, {
    "name" : "Kiribati",
    "id" : "KI"
  }, {
    "name" : "Comoros",
    "id" : "KM"
  }, {
    "name" : "Saint Kitts And Nevis",
    "id" : "KN"
  }, {
    "name" : "North Korea",
    "id" : "KP"
  }, {
    "name" : "South Korea",
    "id" : "KR"
  }, {
    "name" : "Kuwait",
    "id" : "KW"
  }, {
    "name" : "Cayman Islands",
    "id" : "KY"
  }, {
    "name" : "Kazakhstan",
    "id" : "KZ"
  }, {
    "name" : "Laos",
    "id" : "LA"
  }, {
    "name" : "Lebanon",
    "id" : "LB"
  }, {
    "name" : "Saint Lucia",
    "id" : "LC"
  }, {
    "name" : "Liechtenstein",
    "id" : "LI"
  }, {
    "name" : "Sri Lanka",
    "id" : "LK"
  }, {
    "name" : "Liberia",
    "id" : "LR"
  }, {
    "name" : "Lesotho",
    "id" : "LS"
  }, {
    "name" : "Lithuania",
    "id" : "LT"
  }, {
    "name" : "Luxembourg",
    "id" : "LU"
  }, {
    "name" : "Latvia",
    "id" : "LV"
  }, {
    "name" : "Libya",
    "id" : "LY"
  }, {
    "name" : "Morocco",
    "id" : "MA"
  }, {
    "name" : "Monaco",
    "id" : "MC"
  }, {
    "name" : "Moldova",
    "id" : "MD"
  }, {
    "name" : "Montenegro",
    "id" : "ME"
  }, {
    "name" : "Saint Martin",
    "id" : "MF"
  }, {
    "name" : "Madagascar",
    "id" : "MG"
  }, {
    "name" : "Marshall Islands",
    "id" : "MH"
  }, {
    "name" : "Macedonia",
    "id" : "MK"
  }, {
    "name" : "Mali",
    "id" : "ML"
  }, {
    "name" : "Myanmar",
    "id" : "MM"
  }, {
    "name" : "Mongolia",
    "id" : "MN"
  }, {
    "name" : "Macao",
    "id" : "MO"
  }, {
    "name" : "Northern Mariana Islands",
    "id" : "MP"
  }, {
    "name" : "Martinique",
    "id" : "MQ"
  }, {
    "name" : "Mauritania",
    "id" : "MR"
  }, {
    "name" : "Montserrat",
    "id" : "MS"
  }, {
    "name" : "Malta",
    "id" : "MT"
  }, {
    "name" : "Mauritius",
    "id" : "MU"
  }, {
    "name" : "Maldives",
    "id" : "MV"
  }, {
    "name" : "Malawi",
    "id" : "MW"
  }, {
    "name" : "Mexico",
    "id" : "MX"
  }, {
    "name" : "Malaysia",
    "id" : "MY"
  }, {
    "name" : "Mozambique",
    "id" : "MZ"
  }, {
    "name" : "Namibia",
    "id" : "NA"
  }, {
    "name" : "New Caledonia",
    "id" : "NC"
  }, {
    "name" : "Niger",
    "id" : "NE"
  }, {
    "name" : "Norfolk Island",
    "id" : "NF"
  }, {
    "name" : "Nigeria",
    "id" : "NG"
  }, {
    "name" : "Nicaragua",
    "id" : "NI"
  }, {
    "name" : "Netherlands",
    "id" : "NL"
  }, {
    "name" : "Norway",
    "id" : "NO"
  }, {
    "name" : "Nepal",
    "id" : "NP"
  }, {
    "name" : "Nauru",
    "id" : "NR"
  }, {
    "name" : "Niue",
    "id" : "NU"
  }, {
    "name" : "New Zealand",
    "id" : "NZ"
  }, {
    "name" : "Oman",
    "id" : "OM"
  }, {
    "name" : "Panama",
    "id" : "PA"
  }, {
    "name" : "Peru",
    "id" : "PE"
  }, {
    "name" : "French Polynesia",
    "id" : "PF"
  }, {
    "name" : "Papua New Guinea",
    "id" : "PG"
  }, {
    "name" : "Philippines",
    "id" : "PH"
  }, {
    "name" : "Pakistan",
    "id" : "PK"
  }, {
    "name" : "Poland",
    "id" : "PL"
  }, {
    "name" : "Saint Pierre And Miquelon",
    "id" : "PM"
  }, {
    "name" : "Pitcairn",
    "id" : "PN"
  } ],
  "countries" : {
    "Papua New Guinea" : "en_PG",
    "Cambodia" : "km_KH",
    "Kazakhstan" : "ru_KZ",
    "Paraguay" : "es_PY",
    "Syria" : "ar_SY",
    "Bahamas" : "en_BS",
    "Solomon Islands" : "en_SB",
    "Montserrat" : "en_MS",
    "Mali" : "fr_ML",
    "Marshall Islands" : "en_MH",
    "Guadeloupe" : "fr_GP",
    "Panama" : "es_PA",
    "Laos" : "lo_LA",
    "Vatican" : "it_VA",
    "Argentina" : "es_AR",
    "Falkland Islands" : "en_FK",
    "Virgin Islands" : "en_VI",
    "Seychelles" : "en_SC",
    "Belize" : "en_BZ",
    "Zambia" : "en_ZM",
    "Bahrain" : "ar_BH",
    "Congo" : "fr_CG",
    "Namibia" : "en_NA",
    "Comoros" : "fr_KM",
    "Faroe Islands" : "fo_FO",
    "Finland" : "fi_FI",
    "Netherlands Antilles" : "nl_AN",
    "Georgia" : "ka_GE",
    "Yemen" : "ar_YE",
    "Eritrea" : "en_ER",
    "Puerto Rico" : "es_PR",
    "Aruba" : "nl_AW",
    "Madagascar" : "en_MG",
    "Libya" : "ar_LY",
    "Sweden" : "sv_SE",
    "Malawi" : "en_MW",
    "Andorra" : "ca_AD",
    "Liechtenstein" : "de_LI",
    "Algerian" : "ar_DZ",
    "Poland" : "pl_PL",
    "Bulgaria" : "bg_BG",
    "Jordan" : "ar_JO",
    "Tunisia" : "ar_TN",
    "Tuvalu" : "en_TV",
    "United Arab Emirates" : "ar_AE",
    "Kenya" : "sw_KE",
    "French Polynesia" : "fr_PF",
    "Brunei" : "ms_BN",
    "Djibouti" : "ar_DJ",
    "Lebanon" : "ar_LB",
    "Azerbaijan" : "az_AZ",
    "Cuba" : "es_CU",
    "Czech Republic" : "cs_CZ",
    "Mauritania" : "ar_MR",
    "Saint Lucia" : "en_LC",
    "Mayotte" : "fr_YT",
    "Israel" : "iw_IL",
    "San Marino" : "it_SM",
    "Australia" : "en_AU",
    "Tajikistan" : "fa_TJ",
    "Myanmar" : "my_MM",
    "Cameroon" : "fr_CM",
    "Gibraltar" : "en_GI",
    "Cyprus" : "el_CY",
    "Northern Mariana Islands" : "en_MP",
    "Malaysia" : "ms_MY",
    "BelgiumFrench" : "fr_BE",
    "dIvoire" : "fr_CI",
    "Iceland" : "is_IS",
    "Oman" : "ar_OM",
    "Armenia" : "hy_AM",
    "Gabon" : "fr_GA",
    "CanadaFrench" : "fr_CA",
    "Brazil" : "pt_BR",
    "Slovenia" : "sl_SI",
    "LuxembourgFrench" : "fr_LU",
    "Antigua and Barbuda" : "en_AG",
    "Colombia" : "es_CO",
    "Ecuador" : "es_EC",
    "Moldova" : "ro_MD",
    "Vanuatu" : "bi_VU",
    "United States Minor Outlying Islands" : "en_UM",
    "Cocos Islands" : "en_CC",
    "Honduras" : "es_HN",
    "Italy" : "it_IT",
    "Antarctica" : "en_AQ",
    "Nauru" : "en_NR",
    "SwitzerlandFrench" : "fr_CH",
    "Haiti" : "fr_HT",
    "Afghanistan" : "ps_AF",
    "Burundi" : "fr_BI",
    "CanadaEnglish" : "en_CA",
    "Singapore" : "en_SG",
    "French Guiana" : "fr_GF",
    "GuineaBissau" : "pt_GW",
    "American Samoa" : "en_AS",
    "Christmas Island" : "en_CX",
    "Russia" : "ru_RU",
    "Netherlands" : "nl_NL",
    "China" : "zh_CN",
    "Martinique" : "fr_MQ",
    "The Democratic Republic Of Congo" : "fr_CD",
    "Kyrgyzstan" : "uz_KG",
    "Wallis And Futuna" : "fr_WF",
    "Reunion" : "fr_RE",
    "Saint Pierre And Miquelon" : "fr_PM",
    "Bhutan" : "en_BT",
    "Romania" : "ro_RO",
    "Togo" : "fr_TG",
    "Philippines" : "en_PH",
    "Uzbekistan" : "uz_UZ",
    "Pitcairn" : "en_PN",
    "British Virgin Islands" : "en_VG",
    "Zimbabwe" : "en_ZW",
    "British Indian Ocean Territory" : "en_IO",
    "Dominica" : "en_DM",
    "Indonesia" : "id_ID",
    "Benin" : "fr_BJ",
    "Angola" : "pt_AO",
    "Sudan" : "ar_SD",
    "Portugal" : "pt_PT",
    "New Caledonia" : "fr_NC",
    "Grenada" : "en_GD",
    "North Korea" : "ko_KP",
    "Cayman Islands" : "en_KY",
    "Greece" : "el_GR",
    "Latvia" : "lv_LV",
    "Mongolia" : "mn_MN",
    "Iran" : "fa_IR",
    "Morocco" : "ar_MA",
    "Guatemala" : "es_GT",
    "Guyana" : "en_GY",
    "Iraq" : "ar_IQ",
    "Chile" : "es_CL",
    "Nepal" : "ne_NP",
    "SpainCatalan" : "ca_ES",
    "Tanzania" : "sw_TZ",
    "Ukraine" : "uk_UA",
    "Ghana" : "en_GH",
    "Anguilla" : "en_AI",
    "Saint Vincent And The Grenadines" : "en_VC",
    "SwitzerlandItalian" : "it_CH",
    "India" : "en_IN",
    "Maldives" : "dv_MV",
    "Turkey" : "tr_TR",
    "Taiwan" : "zh_TW",
    "South Africa" : "en_ZA",
    "Trinidad and Tobago" : "en_TT",
    "Bermuda" : "en_BM",
    "Central African Republic" : "fr_CF",
    "Jamaica" : "en_JM",
    "Peru" : "es_PE",
    "Turkmenistan" : "tk_TM",
    "Germany" : "de_DE",
    "Fiji" : "fj_FJ",
    "Tokelau" : "en_TK",
    "Hong Kong" : "zh_HK",
    "Guinea" : "fr_GN",
    "United States" : "en_US",
    "Chad" : "ar_TD",
    "Somalia" : "so_SO",
    "Thailand" : "th_TH",
    "Equatorial Guinea" : "es_GQ",
    "Kiribati" : "en_KI",
    "Costa Rica" : "es_CR",
    "Vietnam" : "vi_VN",
    "Kuwait" : "ar_KW",
    "Nigeria" : "en_NG",
    "Croatia" : "hr_HR",
    "Sao Tome And Principe" : "pt_ST",
    "Cook Islands" : "en_CK",
    "Sri Lanka" : "si_LK",
    "Uruguay" : "es_UY",
    "United Kingdom" : "en_GB",
    "Samoa" : "en_WS",
    "Palestine" : "ar_PS",
    "Liberia" : "en_LR",
    "Venezuela" : "es_VE",
    "Burkina Faso" : "fr_BF",
    "Swaziland" : "en_SZ",
    "Palau" : "en_PW",
    "Turks And Caicos Islands" : "en_TC",
    "Estonia" : "et_EE",
    "Niue" : "en_NU",
    "Heard Island And McDonald Islands" : "en_HM",
    "Svalbard And Jan Mayen" : "no_SJ",
    "BelgiumDutch" : "nl_BE",
    "SpainSpanish" : "es_ES",
    "Austria" : "de_AT",
    "South Korea" : "ko_KR",
    "Mozambique" : "pt_MZ",
    "El Salvador" : "es_SV",
    "Monaco" : "fr_MC",
    "Guam" : "en_GU",
    "Lesotho" : "en_LS",
    "Tonga" : "to_TO",
    "Western Sahara" : "ar_EH",
    "Hungary" : "hu_HU",
    "land Islands" : "sv_AX",
    "Japan" : "ja_JP",
    "Belarus" : "be_BY",
    "SwitzerlandGerman" : "de_CH",
    "Mauritius" : "en_MU",
    "Bouvet Island" : "no_BV",
    "Norfolk Island" : "en_NF",
    "New Zealand" : "en_NZ",
    "Senegal" : "fr_SN",
    "TimorLeste" : "pt_TL",
    "Macedonia" : "mk_MK",
    "Ethiopia" : "am_ET",
    "Egypt" : "ar_EG",
    "Sierra Leone" : "en_SL",
    "Bolivia" : "es_BO",
    "LuxembourgGerman" : "de_LU",
    "Malta" : "mt_MT",
    "Saudi Arabia" : "ar_SA",
    "Cape Verde" : "pt_CV",
    "South Georgia And The South Sandwich Islands" : "en_GS",
    "Pakistan" : "en_PK",
    "Kosovo" : "en_XK",
    "Gambia" : "en_GM",
    "Ireland" : "en_IE",
    "Qatar" : "ar_QA",
    "Serbia and Montenegro" : "sr_CS",
    "Slovakia" : "sk_SK",
    "France" : "fr_FR",
    "Lithuania" : "lt_LT",
    "Bosnia and Herzegovina" : "bs_BA",
    "Albanian" : "sq_AL",
    "Niger" : "fr_NE",
    "Rwanda" : "rw_RW",
    "Saint Kitts And Nevis" : "en_KN",
    "French Southern Territories" : "fr_TF",
    "Bangladesh" : "bn_BD",
    "Barbados" : "en_BB",
    "Nicaragua" : "es_NI",
    "Norway" : "no_NO",
    "Botswana" : "en_BW",
    "Macao" : "zh_MO",
    "Denmark" : "da_DK",
    "Dominican Republic" : "es_DO",
    "Mexico" : "es_MX",
    "Uganda" : "en_UG",
    "Micronesia" : "en_FM",
    "Suriname" : "nl_SR",
    "Greenland" : "kl_GL",
    "Saint Helena" : "en_SH"
  }
}

List all languages

This API lists the languages that are available for listing in Zoho Desk.

GET /api/v1/languages

OAuth Scope

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/languages
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "languages" : {
    "Italian" : "it_IT",
    "French" : "fr_FR",
    "Russian" : "ru_RU",
    "English (United States)" : "en_US",
    "Chinese" : "zh_CN",
    "Danish" : "da_DK",
    "Spanish" : "es_ES",
    "German" : "de_DE",
    "Japanese" : "ja_JP",
    "Dutch" : "nl_NL",
    "Turkish" : "tr_TR",
    "Portuguese (Brazil)" : "pt_BR"
  }
}

List all time zones

This API lists the time zones that are available for listing in Zoho Desk.

GET /api/v1/timeZones

OAuth Scope

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/timeZones
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Abidjan )",
    "id" : "Africa/Abidjan"
  }, {
    "name" : "( GMT 0:00 ) Ghana Mean Time( Africa/Accra )",
    "id" : "Africa/Accra"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Addis_Ababa )",
    "id" : "Africa/Addis_Ababa"
  }, {
    "name" : "( GMT 0:00 ) Central European Time( Africa/Algiers )",
    "id" : "Africa/Algiers"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Asmara )",
    "id" : "Africa/Asmara"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Asmera )",
    "id" : "Africa/Asmera"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Bamako )",
    "id" : "Africa/Bamako"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Bangui )",
    "id" : "Africa/Bangui"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Banjul )",
    "id" : "Africa/Banjul"
  }, {
    "name" : "( GMT -1:00 ) Greenwich Mean Time( Africa/Bissau )",
    "id" : "Africa/Bissau"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Blantyre )",
    "id" : "Africa/Blantyre"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Brazzaville )",
    "id" : "Africa/Brazzaville"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Bujumbura )",
    "id" : "Africa/Bujumbura"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Africa/Cairo )",
    "id" : "Africa/Cairo"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Africa/Casablanca )",
    "id" : "Africa/Casablanca"
  }, {
    "name" : "( GMT 0:00 ) Central European Summer Time( Africa/Ceuta )",
    "id" : "Africa/Ceuta"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Conakry )",
    "id" : "Africa/Conakry"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Dakar )",
    "id" : "Africa/Dakar"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Dar_es_Salaam )",
    "id" : "Africa/Dar_es_Salaam"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Djibouti )",
    "id" : "Africa/Djibouti"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Douala )",
    "id" : "Africa/Douala"
  }, {
    "name" : "( GMT -1:00 ) Western European Summer Time( Africa/El_Aaiun )",
    "id" : "Africa/El_Aaiun"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Freetown )",
    "id" : "Africa/Freetown"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Gaborone )",
    "id" : "Africa/Gaborone"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Harare )",
    "id" : "Africa/Harare"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Johannesburg )",
    "id" : "Africa/Johannesburg"
  }, {
    "name" : "( GMT 2:00 ) Eastern African Time( Africa/Juba )",
    "id" : "Africa/Juba"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Kampala )",
    "id" : "Africa/Kampala"
  }, {
    "name" : "( GMT 2:00 ) Eastern African Time( Africa/Khartoum )",
    "id" : "Africa/Khartoum"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Kigali )",
    "id" : "Africa/Kigali"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Kinshasa )",
    "id" : "Africa/Kinshasa"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Lagos )",
    "id" : "Africa/Lagos"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Libreville )",
    "id" : "Africa/Libreville"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Lome )",
    "id" : "Africa/Lome"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Luanda )",
    "id" : "Africa/Luanda"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Lubumbashi )",
    "id" : "Africa/Lubumbashi"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Lusaka )",
    "id" : "Africa/Lusaka"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Malabo )",
    "id" : "Africa/Malabo"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Maputo )",
    "id" : "Africa/Maputo"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Maseru )",
    "id" : "Africa/Maseru"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Mbabane )",
    "id" : "Africa/Mbabane"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Mogadishu )",
    "id" : "Africa/Mogadishu"
  }, {
    "name" : "( GMT 0:44 ) Greenwich Mean Time( Africa/Monrovia )",
    "id" : "Africa/Monrovia"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Nairobi )",
    "id" : "Africa/Nairobi"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Ndjamena )",
    "id" : "Africa/Ndjamena"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Niamey )",
    "id" : "Africa/Niamey"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Nouakchott )",
    "id" : "Africa/Nouakchott"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Ouagadougou )",
    "id" : "Africa/Ouagadougou"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Porto-Novo )",
    "id" : "Africa/Porto-Novo"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Sao_Tome )",
    "id" : "Africa/Sao_Tome"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Timbuktu )",
    "id" : "Africa/Timbuktu"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Africa/Tripoli )",
    "id" : "Africa/Tripoli"
  }, {
    "name" : "( GMT 1:00 ) Central European Time( Africa/Tunis )",
    "id" : "Africa/Tunis"
  }, {
    "name" : "( GMT 2:00 ) Western African Summer Time( Africa/Windhoek )",
    "id" : "Africa/Windhoek"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( America/Adak )",
    "id" : "America/Adak"
  }, {
    "name" : "( GMT -10:00 ) Alaska Daylight Time( America/Anchorage )",
    "id" : "America/Anchorage"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Anguilla )",
    "id" : "America/Anguilla"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Antigua )",
    "id" : "America/Antigua"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Araguaina )",
    "id" : "America/Araguaina"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Buenos_Aires )",
    "id" : "America/Argentina/Buenos_Aires"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Catamarca )",
    "id" : "America/Argentina/Catamarca"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/ComodRivadavia )",
    "id" : "America/Argentina/ComodRivadavia"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Cordoba )",
    "id" : "America/Argentina/Cordoba"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Jujuy )",
    "id" : "America/Argentina/Jujuy"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/La_Rioja )",
    "id" : "America/Argentina/La_Rioja"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Mendoza )",
    "id" : "America/Argentina/Mendoza"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Rio_Gallegos )",
    "id" : "America/Argentina/Rio_Gallegos"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Salta )",
    "id" : "America/Argentina/Salta"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/San_Juan )",
    "id" : "America/Argentina/San_Juan"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/San_Luis )",
    "id" : "America/Argentina/San_Luis"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Tucuman )",
    "id" : "America/Argentina/Tucuman"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Ushuaia )",
    "id" : "America/Argentina/Ushuaia"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Aruba )",
    "id" : "America/Aruba"
  }, {
    "name" : "( GMT -4:00 ) Paraguay Summer Time( America/Asuncion )",
    "id" : "America/Asuncion"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Atikokan )",
    "id" : "America/Atikokan"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( America/Atka )",
    "id" : "America/Atka"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Bahia )",
    "id" : "America/Bahia"
  }, {
    "name" : "( GMT -8:00 ) Central Daylight Time( America/Bahia_Banderas )",
    "id" : "America/Bahia_Banderas"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Barbados )",
    "id" : "America/Barbados"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Belem )",
    "id" : "America/Belem"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Belize )",
    "id" : "America/Belize"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Blanc-Sablon )",
    "id" : "America/Blanc-Sablon"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Boa_Vista )",
    "id" : "America/Boa_Vista"
  }, {
    "name" : "( GMT -5:00 ) Colombia Time( America/Bogota )",
    "id" : "America/Bogota"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Boise )",
    "id" : "America/Boise"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Buenos_Aires )",
    "id" : "America/Buenos_Aires"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Cambridge_Bay )",
    "id" : "America/Cambridge_Bay"
  }, {
    "name" : "( GMT -4:00 ) Amazon Summer Time( America/Campo_Grande )",
    "id" : "America/Campo_Grande"
  }, {
    "name" : "( GMT -6:00 ) Eastern Standard Time( America/Cancun )",
    "id" : "America/Cancun"
  }, {
    "name" : "( GMT -4:00 ) Venezuela Time( America/Caracas )",
    "id" : "America/Caracas"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Catamarca )",
    "id" : "America/Catamarca"
  }, {
    "name" : "( GMT -3:00 ) French Guiana Time( America/Cayenne )",
    "id" : "America/Cayenne"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Cayman )",
    "id" : "America/Cayman"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Chicago )",
    "id" : "America/Chicago"
  }, {
    "name" : "( GMT -6:00 ) Mountain Daylight Time( America/Chihuahua )",
    "id" : "America/Chihuahua"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Coral_Harbour )",
    "id" : "America/Coral_Harbour"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Cordoba )",
    "id" : "America/Cordoba"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Costa_Rica )",
    "id" : "America/Costa_Rica"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Creston )",
    "id" : "America/Creston"
  }, {
    "name" : "( GMT -4:00 ) Amazon Summer Time( America/Cuiaba )",
    "id" : "America/Cuiaba"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Curacao )",
    "id" : "America/Curacao"
  }, {
    "name" : "( GMT -3:00 ) Greenwich Mean Time( America/Danmarkshavn )",
    "id" : "America/Danmarkshavn"
  }, {
    "name" : "( GMT -9:00 ) Pacific Daylight Time( America/Dawson )",
    "id" : "America/Dawson"
  }, {
    "name" : "( GMT -8:00 ) Mountain Standard Time( America/Dawson_Creek )",
    "id" : "America/Dawson_Creek"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Denver )",
    "id" : "America/Denver"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Detroit )",
    "id" : "America/Detroit"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Dominica )",
    "id" : "America/Dominica"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Edmonton )",
    "id" : "America/Edmonton"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Eirunepe )",
    "id" : "America/Eirunepe"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/El_Salvador )",
    "id" : "America/El_Salvador"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Ensenada )",
    "id" : "America/Ensenada"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Fort_Nelson )",
    "id" : "America/Fort_Nelson"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Fort_Wayne )",
    "id" : "America/Fort_Wayne"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Fortaleza )",
    "id" : "America/Fortaleza"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Glace_Bay )",
    "id" : "America/Glace_Bay"
  }, {
    "name" : "( GMT -3:00 ) Western Greenland Summer Time( America/Godthab )",
    "id" : "America/Godthab"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Goose_Bay )",
    "id" : "America/Goose_Bay"
  }, {
    "name" : "( GMT -5:00 ) Atlantic Standard Time( America/Grand_Turk )",
    "id" : "America/Grand_Turk"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Grenada )",
    "id" : "America/Grenada"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Guadeloupe )",
    "id" : "America/Guadeloupe"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Guatemala )",
    "id" : "America/Guatemala"
  }, {
    "name" : "( GMT -5:00 ) Ecuador Time( America/Guayaquil )",
    "id" : "America/Guayaquil"
  }, {
    "name" : "( GMT -3:45 ) Guyana Time( America/Guyana )",
    "id" : "America/Guyana"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Halifax )",
    "id" : "America/Halifax"
  }, {
    "name" : "( GMT -5:00 ) Cuba Daylight Time( America/Havana )",
    "id" : "America/Havana"
  }, {
    "name" : "( GMT -8:00 ) Mountain Standard Time( America/Hermosillo )",
    "id" : "America/Hermosillo"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Indianapolis )",
    "id" : "America/Indiana/Indianapolis"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Indiana/Knox )",
    "id" : "America/Indiana/Knox"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Marengo )",
    "id" : "America/Indiana/Marengo"
  }, {
    "name" : "( GMT -6:00 ) Eastern Daylight Time( America/Indiana/Petersburg )",
    "id" : "America/Indiana/Petersburg"
  }, {
    "name" : "( GMT -5:00 ) Central Daylight Time( America/Indiana/Tell_City )",
    "id" : "America/Indiana/Tell_City"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Vevay )",
    "id" : "America/Indiana/Vevay"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Vincennes )",
    "id" : "America/Indiana/Vincennes"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Winamac )",
    "id" : "America/Indiana/Winamac"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indianapolis )",
    "id" : "America/Indianapolis"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( America/Inuvik )",
    "id" : "America/Inuvik"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Iqaluit )",
    "id" : "America/Iqaluit"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Jamaica )",
    "id" : "America/Jamaica"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Jujuy )",
    "id" : "America/Jujuy"
  }, {
    "name" : "( GMT -8:00 ) Alaska Daylight Time( America/Juneau )",
    "id" : "America/Juneau"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Kentucky/Louisville )",
    "id" : "America/Kentucky/Louisville"
  }, {
    "name" : "( GMT -6:00 ) Eastern Daylight Time( America/Kentucky/Monticello )",
    "id" : "America/Kentucky/Monticello"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Knox_IN )",
    "id" : "America/Knox_IN"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Kralendijk )",
    "id" : "America/Kralendijk"
  }, {
    "name" : "( GMT -4:00 ) Bolivia Time( America/La_Paz )",
    "id" : "America/La_Paz"
  }, {
    "name" : "( GMT -5:00 ) Peru Time( America/Lima )",
    "id" : "America/Lima"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Los_Angeles )",
    "id" : "America/Los_Angeles"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Louisville )",
    "id" : "America/Louisville"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Lower_Princes )",
    "id" : "America/Lower_Princes"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Maceio )",
    "id" : "America/Maceio"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Managua )",
    "id" : "America/Managua"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Manaus )",
    "id" : "America/Manaus"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Marigot )",
    "id" : "America/Marigot"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Martinique )",
    "id" : "America/Martinique"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Matamoros )",
    "id" : "America/Matamoros"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( America/Mazatlan )",
    "id" : "America/Mazatlan"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Mendoza )",
    "id" : "America/Mendoza"
  }, {
    "name" : "( GMT -5:00 ) Central Daylight Time( America/Menominee )",
    "id" : "America/Menominee"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Merida )",
    "id" : "America/Merida"
  }, {
    "name" : "( GMT -8:00 ) Pacific Standard Time( America/Metlakatla )",
    "id" : "America/Metlakatla"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Mexico_City )",
    "id" : "America/Mexico_City"
  }, {
    "name" : "( GMT -4:00 ) Pierre & Miquelon Daylight Time( America/Miquelon )",
    "id" : "America/Miquelon"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Moncton )",
    "id" : "America/Moncton"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Monterrey )",
    "id" : "America/Monterrey"
  }, {
    "name" : "( GMT -3:00 ) Uruguay Time( America/Montevideo )",
    "id" : "America/Montevideo"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Montreal )",
    "id" : "America/Montreal"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Montserrat )",
    "id" : "America/Montserrat"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Nassau )",
    "id" : "America/Nassau"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/New_York )",
    "id" : "America/New_York"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Nipigon )",
    "id" : "America/Nipigon"
  }, {
    "name" : "( GMT -11:00 ) Alaska Daylight Time( America/Nome )",
    "id" : "America/Nome"
  }, {
    "name" : "( GMT -2:00 ) Fernando de Noronha Time( America/Noronha )",
    "id" : "America/Noronha"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/Beulah )",
    "id" : "America/North_Dakota/Beulah"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/Center )",
    "id" : "America/North_Dakota/Center"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/New_Salem )",
    "id" : "America/North_Dakota/New_Salem"
  }, {
    "name" : "( GMT -6:00 ) Mountain Daylight Time( America/Ojinaga )",
    "id" : "America/Ojinaga"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Panama )",
    "id" : "America/Panama"
  }, {
    "name" : "( GMT -4:00 ) Eastern Daylight Time( America/Pangnirtung )",
    "id" : "America/Pangnirtung"
  }, {
    "name" : "( GMT -3:30 ) Suriname Time( America/Paramaribo )",
    "id" : "America/Paramaribo"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Phoenix )",
    "id" : "America/Phoenix"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Port-au-Prince )",
    "id" : "America/Port-au-Prince"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Port_of_Spain )",
    "id" : "America/Port_of_Spain"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Porto_Acre )",
    "id" : "America/Porto_Acre"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Porto_Velho )",
    "id" : "America/Porto_Velho"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Puerto_Rico )",
    "id" : "America/Puerto_Rico"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Rainy_River )",
    "id" : "America/Rainy_River"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Rankin_Inlet )",
    "id" : "America/Rankin_Inlet"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Recife )",
    "id" : "America/Recife"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Regina )",
    "id" : "America/Regina"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Resolute )",
    "id" : "America/Resolute"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Rio_Branco )",
    "id" : "America/Rio_Branco"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Rosario )",
    "id" : "America/Rosario"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Santa_Isabel )",
    "id" : "America/Santa_Isabel"
  }, {
    "name" : "( GMT -4:00 ) Brasilia Time( America/Santarem )",
    "id" : "America/Santarem"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( America/Santiago )",
    "id" : "America/Santiago"
  }, {
    "name" : "( GMT -4:30 ) Atlantic Standard Time( America/Santo_Domingo )",
    "id" : "America/Santo_Domingo"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( America/Sao_Paulo )",
    "id" : "America/Sao_Paulo"
  }, {
    "name" : "( GMT -2:00 ) Eastern Greenland Summer Time( America/Scoresbysund )",
    "id" : "America/Scoresbysund"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Shiprock )",
    "id" : "America/Shiprock"
  }, {
    "name" : "( GMT -8:00 ) Alaska Daylight Time( America/Sitka )",
    "id" : "America/Sitka"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Barthelemy )",
    "id" : "America/St_Barthelemy"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( America/St_Johns )",
    "id" : "America/St_Johns"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Kitts )",
    "id" : "America/St_Kitts"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Lucia )",
    "id" : "America/St_Lucia"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Thomas )",
    "id" : "America/St_Thomas"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Vincent )",
    "id" : "America/St_Vincent"
  }, {
    "name" : "( GMT -7:00 ) Central Standard Time( America/Swift_Current )",
    "id" : "America/Swift_Current"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Tegucigalpa )",
    "id" : "America/Tegucigalpa"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Thule )",
    "id" : "America/Thule"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Thunder_Bay )",
    "id" : "America/Thunder_Bay"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Tijuana )",
    "id" : "America/Tijuana"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Toronto )",
    "id" : "America/Toronto"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Tortola )",
    "id" : "America/Tortola"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Vancouver )",
    "id" : "America/Vancouver"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Virgin )",
    "id" : "America/Virgin"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Whitehorse )",
    "id" : "America/Whitehorse"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Winnipeg )",
    "id" : "America/Winnipeg"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( America/Yakutat )",
    "id" : "America/Yakutat"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Yellowknife )",
    "id" : "America/Yellowknife"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Antarctica/Casey )",
    "id" : "Antarctica/Casey"
  }, {
    "name" : "( GMT 7:00 ) Davis Time( Antarctica/Davis )",
    "id" : "Antarctica/Davis"
  }, {
    "name" : "( GMT 10:00 ) Dumont-d'Urville Time( Antarctica/DumontDUrville )",
    "id" : "Antarctica/DumontDUrville"
  }, {
    "name" : "( GMT 11:00 ) Macquarie Island Standard Time( Antarctica/Macquarie )",
    "id" : "Antarctica/Macquarie"
  }, {
    "name" : "( GMT 6:00 ) Mawson Time( Antarctica/Mawson )",
    "id" : "Antarctica/Mawson"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Antarctica/McMurdo )",
    "id" : "Antarctica/McMurdo"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( Antarctica/Palmer )",
    "id" : "Antarctica/Palmer"
  }, {
    "name" : "( GMT 0:00 ) Rothera Time( Antarctica/Rothera )",
    "id" : "Antarctica/Rothera"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Antarctica/South_Pole )",
    "id" : "Antarctica/South_Pole"
  }, {
    "name" : "( GMT 3:00 ) Syowa Time( Antarctica/Syowa )",
    "id" : "Antarctica/Syowa"
  }, {
    "name" : "( GMT 0:00 ) Central European Summer Time( Antarctica/Troll )",
    "id" : "Antarctica/Troll"
  }, {
    "name" : "( GMT 6:00 ) Vostok Time( Antarctica/Vostok )",
    "id" : "Antarctica/Vostok"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Arctic/Longyearbyen )",
    "id" : "Arctic/Longyearbyen"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Aden )",
    "id" : "Asia/Aden"
  }, {
    "name" : "( GMT 6:00 ) Alma-Ata Time( Asia/Almaty )",
    "id" : "Asia/Almaty"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Amman )",
    "id" : "Asia/Amman"
  }, {
    "name" : "( GMT 13:00 ) Anadyr Time( Asia/Anadyr )",
    "id" : "Asia/Anadyr"
  }, {
    "name" : "( GMT 5:00 ) Aqtau Time( Asia/Aqtau )",
    "id" : "Asia/Aqtau"
  }, {
    "name" : "( GMT 5:00 ) Aqtobe Time( Asia/Aqtobe )",
    "id" : "Asia/Aqtobe"
  }, {
    "name" : "( GMT 5:00 ) Turkmenistan Time( Asia/Ashgabat )",
    "id" : "Asia/Ashgabat"
  }, {
    "name" : "( GMT 5:00 ) Turkmenistan Time( Asia/Ashkhabad )",
    "id" : "Asia/Ashkhabad"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Baghdad )",
    "id" : "Asia/Baghdad"
  }, {
    "name" : "( GMT 4:00 ) Arabia Standard Time( Asia/Bahrain )",
    "id" : "Asia/Bahrain"
  }, {
    "name" : "( GMT 4:00 ) Azerbaijan Summer Time( Asia/Baku )",
    "id" : "Asia/Baku"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Bangkok )",
    "id" : "Asia/Bangkok"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Beirut )",
    "id" : "Asia/Beirut"
  }, {
    "name" : "( GMT 6:00 ) Kirgizstan Time( Asia/Bishkek )",
    "id" : "Asia/Bishkek"
  }, {
    "name" : "( GMT 8:00 ) Brunei Time( Asia/Brunei )",
    "id" : "Asia/Brunei"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Calcutta )",
    "id" : "Asia/Calcutta"
  }, {
    "name" : "( GMT 8:00 ) Irkutsk Time( Asia/Chita )",
    "id" : "Asia/Chita"
  }, {
    "name" : "( GMT 7:00 ) Choibalsan Summer Time( Asia/Choibalsan )",
    "id" : "Asia/Choibalsan"
  }, {
    "name" : "( GMT 7:00 ) China Standard Time( Asia/Chongqing )",
    "id" : "Asia/Chongqing"
  }, {
    "name" : "( GMT 7:00 ) China Standard Time( Asia/Chungking )",
    "id" : "Asia/Chungking"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Colombo )",
    "id" : "Asia/Colombo"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( Asia/Dacca )",
    "id" : "Asia/Dacca"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Damascus )",
    "id" : "Asia/Damascus"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( Asia/Dhaka )",
    "id" : "Asia/Dhaka"
  }, {
    "name" : "( GMT 9:00 ) Timor-Leste Time( Asia/Dili )",
    "id" : "Asia/Dili"
  }, {
    "name" : "( GMT 4:00 ) Gulf Standard Time( Asia/Dubai )",
    "id" : "Asia/Dubai"
  }, {
    "name" : "( GMT 6:00 ) Tajikistan Time( Asia/Dushanbe )",
    "id" : "Asia/Dushanbe"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Gaza )",
    "id" : "Asia/Gaza"
  }, {
    "name" : "( GMT 8:30 ) China Standard Time( Asia/Harbin )",
    "id" : "Asia/Harbin"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Hebron )",
    "id" : "Asia/Hebron"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Ho_Chi_Minh )",
    "id" : "Asia/Ho_Chi_Minh"
  }, {
    "name" : "( GMT 8:00 ) Hong Kong Time( Asia/Hong_Kong )",
    "id" : "Asia/Hong_Kong"
  }, {
    "name" : "( GMT 6:00 ) Hovd Summer Time( Asia/Hovd )",
    "id" : "Asia/Hovd"
  }, {
    "name" : "( GMT 8:00 ) Irkutsk Time( Asia/Irkutsk )",
    "id" : "Asia/Irkutsk"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Istanbul )",
    "id" : "Asia/Istanbul"
  }, {
    "name" : "( GMT 7:00 ) West Indonesia Time( Asia/Jakarta )",
    "id" : "Asia/Jakarta"
  }, {
    "name" : "( GMT 9:00 ) East Indonesia Time( Asia/Jayapura )",
    "id" : "Asia/Jayapura"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Asia/Jerusalem )",
    "id" : "Asia/Jerusalem"
  }, {
    "name" : "( GMT 4:30 ) Afghanistan Time( Asia/Kabul )",
    "id" : "Asia/Kabul"
  }, {
    "name" : "( GMT 12:00 ) Petropavlovsk-Kamchatski Time( Asia/Kamchatka )",
    "id" : "Asia/Kamchatka"
  }, {
    "name" : "( GMT 5:00 ) Pakistan Time( Asia/Karachi )",
    "id" : "Asia/Karachi"
  }, {
    "name" : "( GMT 5:00 ) Xinjiang Standard Time( Asia/Kashgar )",
    "id" : "Asia/Kashgar"
  }, {
    "name" : "( GMT 5:30 ) Nepal Time( Asia/Kathmandu )",
    "id" : "Asia/Kathmandu"
  }, {
    "name" : "( GMT 5:30 ) Nepal Time( Asia/Katmandu )",
    "id" : "Asia/Katmandu"
  }, {
    "name" : "( GMT 9:00 ) Khandyga Time( Asia/Khandyga )",
    "id" : "Asia/Khandyga"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Kolkata )",
    "id" : "Asia/Kolkata"
  }, {
    "name" : "( GMT 7:00 ) Krasnoyarsk Time( Asia/Krasnoyarsk )",
    "id" : "Asia/Krasnoyarsk"
  }, {
    "name" : "( GMT 7:30 ) Malaysia Time( Asia/Kuala_Lumpur )",
    "id" : "Asia/Kuala_Lumpur"
  }, {
    "name" : "( GMT 8:00 ) Malaysia Time( Asia/Kuching )",
    "id" : "Asia/Kuching"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Kuwait )",
    "id" : "Asia/Kuwait"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Macao )",
    "id" : "Asia/Macao"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Macau )",
    "id" : "Asia/Macau"
  }, {
    "name" : "( GMT 11:00 ) Magadan Time( Asia/Magadan )",
    "id" : "Asia/Magadan"
  }, {
    "name" : "( GMT 8:00 ) Central Indonesia Time( Asia/Makassar )",
    "id" : "Asia/Makassar"
  }, {
    "name" : "( GMT 8:00 ) Philippines Time( Asia/Manila )",
    "id" : "Asia/Manila"
  }, {
    "name" : "( GMT 4:00 ) Gulf Standard Time( Asia/Muscat )",
    "id" : "Asia/Muscat"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Nicosia )",
    "id" : "Asia/Nicosia"
  }, {
    "name" : "( GMT 7:00 ) Krasnoyarsk Time( Asia/Novokuznetsk )",
    "id" : "Asia/Novokuznetsk"
  }, {
    "name" : "( GMT 7:00 ) Novosibirsk Time( Asia/Novosibirsk )",
    "id" : "Asia/Novosibirsk"
  }, {
    "name" : "( GMT 6:00 ) Omsk Time( Asia/Omsk )",
    "id" : "Asia/Omsk"
  }, {
    "name" : "( GMT 5:00 ) Oral Time( Asia/Oral )",
    "id" : "Asia/Oral"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Phnom_Penh )",
    "id" : "Asia/Phnom_Penh"
  }, {
    "name" : "( GMT 8:00 ) West Indonesia Time( Asia/Pontianak )",
    "id" : "Asia/Pontianak"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( Asia/Pyongyang )",
    "id" : "Asia/Pyongyang"
  }, {
    "name" : "( GMT 4:00 ) Arabia Standard Time( Asia/Qatar )",
    "id" : "Asia/Qatar"
  }, {
    "name" : "( GMT 5:00 ) Qyzylorda Time( Asia/Qyzylorda )",
    "id" : "Asia/Qyzylorda"
  }, {
    "name" : "( GMT 6:30 ) Myanmar Time( Asia/Rangoon )",
    "id" : "Asia/Rangoon"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Riyadh )",
    "id" : "Asia/Riyadh"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Saigon )",
    "id" : "Asia/Saigon"
  }, {
    "name" : "( GMT 11:00 ) Sakhalin Time( Asia/Sakhalin )",
    "id" : "Asia/Sakhalin"
  }, {
    "name" : "( GMT 5:00 ) Uzbekistan Time( Asia/Samarkand )",
    "id" : "Asia/Samarkand"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( Asia/Seoul )",
    "id" : "Asia/Seoul"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Shanghai )",
    "id" : "Asia/Shanghai"
  }, {
    "name" : "( GMT 7:30 ) Singapore Time( Asia/Singapore )",
    "id" : "Asia/Singapore"
  }, {
    "name" : "( GMT 11:00 ) Srednekolymsk Time( Asia/Srednekolymsk )",
    "id" : "Asia/Srednekolymsk"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Taipei )",
    "id" : "Asia/Taipei"
  }, {
    "name" : "( GMT 6:00 ) Uzbekistan Time( Asia/Tashkent )",
    "id" : "Asia/Tashkent"
  }, {
    "name" : "( GMT 4:00 ) Georgia Time( Asia/Tbilisi )",
    "id" : "Asia/Tbilisi"
  }, {
    "name" : "( GMT 3:30 ) Iran Daylight Time( Asia/Tehran )",
    "id" : "Asia/Tehran"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Asia/Tel_Aviv )",
    "id" : "Asia/Tel_Aviv"
  }, {
    "name" : "( GMT 5:30 ) Bhutan Time( Asia/Thimbu )",
    "id" : "Asia/Thimbu"
  }, {
    "name" : "( GMT 5:30 ) Bhutan Time( Asia/Thimphu )",
    "id" : "Asia/Thimphu"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( Asia/Tokyo )",
    "id" : "Asia/Tokyo"
  }, {
    "name" : "( GMT 8:00 ) Central Indonesia Time( Asia/Ujung_Pandang )",
    "id" : "Asia/Ujung_Pandang"
  }, {
    "name" : "( GMT 7:00 ) Ulaanbaatar Summer Time( Asia/Ulaanbaatar )",
    "id" : "Asia/Ulaanbaatar"
  }, {
    "name" : "( GMT 7:00 ) Ulaanbaatar Summer Time( Asia/Ulan_Bator )",
    "id" : "Asia/Ulan_Bator"
  }, {
    "name" : "( GMT 6:00 ) Xinjiang Standard Time( Asia/Urumqi )",
    "id" : "Asia/Urumqi"
  }, {
    "name" : "( GMT 10:00 ) Ust-Nera Time( Asia/Ust-Nera )",
    "id" : "Asia/Ust-Nera"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Vientiane )",
    "id" : "Asia/Vientiane"
  }, {
    "name" : "( GMT 10:00 ) Vladivostok Time( Asia/Vladivostok )",
    "id" : "Asia/Vladivostok"
  }, {
    "name" : "( GMT 9:00 ) Yakutsk Time( Asia/Yakutsk )",
    "id" : "Asia/Yakutsk"
  }, {
    "name" : "( GMT 5:00 ) Yekaterinburg Time( Asia/Yekaterinburg )",
    "id" : "Asia/Yekaterinburg"
  }, {
    "name" : "( GMT 4:00 ) Armenia Time( Asia/Yerevan )",
    "id" : "Asia/Yerevan"
  }, {
    "name" : "( GMT -1:00 ) Azores Summer Time( Atlantic/Azores )",
    "id" : "Atlantic/Azores"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( Atlantic/Bermuda )",
    "id" : "Atlantic/Bermuda"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Canary )",
    "id" : "Atlantic/Canary"
  }, {
    "name" : "( GMT -2:00 ) Cape Verde Time( Atlantic/Cape_Verde )",
    "id" : "Atlantic/Cape_Verde"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Faeroe )",
    "id" : "Atlantic/Faeroe"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Faroe )",
    "id" : "Atlantic/Faroe"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Atlantic/Jan_Mayen )",
    "id" : "Atlantic/Jan_Mayen"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Madeira )",
    "id" : "Atlantic/Madeira"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Atlantic/Reykjavik )",
    "id" : "Atlantic/Reykjavik"
  }, {
    "name" : "( GMT -2:00 ) South Georgia Standard Time( Atlantic/South_Georgia )",
    "id" : "Atlantic/South_Georgia"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Atlantic/St_Helena )",
    "id" : "Atlantic/St_Helena"
  }, {
    "name" : "( GMT -4:00 ) Falkland Is. Time( Atlantic/Stanley )",
    "id" : "Atlantic/Stanley"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/ACT )",
    "id" : "Australia/ACT"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia)( Australia/Adelaide )",
    "id" : "Australia/Adelaide"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Brisbane )",
    "id" : "Australia/Brisbane"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia/New South Wales)( Australia/Broken_Hill )",
    "id" : "Australia/Broken_Hill"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Canberra )",
    "id" : "Australia/Canberra"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Currie )",
    "id" : "Australia/Currie"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( Australia/Darwin )",
    "id" : "Australia/Darwin"
  }, {
    "name" : "( GMT 8:45 ) Australian Central Western Standard Time( Australia/Eucla )",
    "id" : "Australia/Eucla"
  }, {
    "name" : "( GMT 11:00 ) Australian Eastern Daylight Time (Tasmania)( Australia/Hobart )",
    "id" : "Australia/Hobart"
  }, {
    "name" : "( GMT 10:00 ) Lord Howe Daylight Time( Australia/LHI )",
    "id" : "Australia/LHI"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Lindeman )",
    "id" : "Australia/Lindeman"
  }, {
    "name" : "( GMT 10:00 ) Lord Howe Daylight Time( Australia/Lord_Howe )",
    "id" : "Australia/Lord_Howe"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (Victoria)( Australia/Melbourne )",
    "id" : "Australia/Melbourne"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/NSW )",
    "id" : "Australia/NSW"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( Australia/North )",
    "id" : "Australia/North"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Australia/Perth )",
    "id" : "Australia/Perth"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Queensland )",
    "id" : "Australia/Queensland"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia)( Australia/South )",
    "id" : "Australia/South"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Sydney )",
    "id" : "Australia/Sydney"
  }, {
    "name" : "( GMT 11:00 ) Australian Eastern Daylight Time (Tasmania)( Australia/Tasmania )",
    "id" : "Australia/Tasmania"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (Victoria)( Australia/Victoria )",
    "id" : "Australia/Victoria"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Australia/West )",
    "id" : "Australia/West"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia/New South Wales)( Australia/Yancowinna )",
    "id" : "Australia/Yancowinna"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( Brazil/Acre )",
    "id" : "Brazil/Acre"
  }, {
    "name" : "( GMT -2:00 ) Fernando de Noronha Time( Brazil/DeNoronha )",
    "id" : "Brazil/DeNoronha"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( Brazil/East )",
    "id" : "Brazil/East"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( Brazil/West )",
    "id" : "Brazil/West"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( CET )",
    "id" : "CET"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( CST6CDT )",
    "id" : "CST6CDT"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( Canada/Atlantic )",
    "id" : "Canada/Atlantic"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( Canada/Central )",
    "id" : "Canada/Central"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( Canada/East-Saskatchewan )",
    "id" : "Canada/East-Saskatchewan"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( Canada/Eastern )",
    "id" : "Canada/Eastern"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( Canada/Mountain )",
    "id" : "Canada/Mountain"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( Canada/Newfoundland )",
    "id" : "Canada/Newfoundland"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Canada/Pacific )",
    "id" : "Canada/Pacific"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( Canada/Saskatchewan )",
    "id" : "Canada/Saskatchewan"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Canada/Yukon )",
    "id" : "Canada/Yukon"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( Chile/Continental )",
    "id" : "Chile/Continental"
  }, {
    "name" : "( GMT -6:00 ) Easter Is. Time( Chile/EasterIsland )",
    "id" : "Chile/EasterIsland"
  }, {
    "name" : "( GMT -5:00 ) Cuba Daylight Time( Cuba )",
    "id" : "Cuba"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( EET )",
    "id" : "EET"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( EST5EDT )",
    "id" : "EST5EDT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Egypt )",
    "id" : "Egypt"
  }, {
    "name" : "( GMT 1:00 ) Irish Summer Time( Eire )",
    "id" : "Eire"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT )",
    "id" : "Etc/GMT"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT+0 )",
    "id" : "Etc/GMT+0"
  }, {
    "name" : "( GMT -1:00 ) GMT-01:00( Etc/GMT+1 )",
    "id" : "Etc/GMT+1"
  }, {
    "name" : "( GMT -10:00 ) GMT-10:00( Etc/GMT+10 )",
    "id" : "Etc/GMT+10"
  }, {
    "name" : "( GMT -11:00 ) GMT-11:00( Etc/GMT+11 )",
    "id" : "Etc/GMT+11"
  }, {
    "name" : "( GMT -12:00 ) GMT-12:00( Etc/GMT+12 )",
    "id" : "Etc/GMT+12"
  }, {
    "name" : "( GMT -2:00 ) GMT-02:00( Etc/GMT+2 )",
    "id" : "Etc/GMT+2"
  }, {
    "name" : "( GMT -3:00 ) GMT-03:00( Etc/GMT+3 )",
    "id" : "Etc/GMT+3"
  }, {
    "name" : "( GMT -4:00 ) GMT-04:00( Etc/GMT+4 )",
    "id" : "Etc/GMT+4"
  }, {
    "name" : "( GMT -5:00 ) GMT-05:00( Etc/GMT+5 )",
    "id" : "Etc/GMT+5"
  }, {
    "name" : "( GMT -6:00 ) GMT-06:00( Etc/GMT+6 )",
    "id" : "Etc/GMT+6"
  }, {
    "name" : "( GMT -7:00 ) GMT-07:00( Etc/GMT+7 )",
    "id" : "Etc/GMT+7"
  }, {
    "name" : "( GMT -8:00 ) GMT-08:00( Etc/GMT+8 )",
    "id" : "Etc/GMT+8"
  }, {
    "name" : "( GMT -9:00 ) GMT-09:00( Etc/GMT+9 )",
    "id" : "Etc/GMT+9"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT-0 )",
    "id" : "Etc/GMT-0"
  }, {
    "name" : "( GMT 1:00 ) GMT+01:00( Etc/GMT-1 )",
    "id" : "Etc/GMT-1"
  }, {
    "name" : "( GMT 10:00 ) GMT+10:00( Etc/GMT-10 )",
    "id" : "Etc/GMT-10"
  }, {
    "name" : "( GMT 11:00 ) GMT+11:00( Etc/GMT-11 )",
    "id" : "Etc/GMT-11"
  }, {
    "name" : "( GMT 12:00 ) GMT+12:00( Etc/GMT-12 )",
    "id" : "Etc/GMT-12"
  }, {
    "name" : "( GMT 13:00 ) GMT+13:00( Etc/GMT-13 )",
    "id" : "Etc/GMT-13"
  }, {
    "name" : "( GMT 14:00 ) GMT+14:00( Etc/GMT-14 )",
    "id" : "Etc/GMT-14"
  }, {
    "name" : "( GMT 2:00 ) GMT+02:00( Etc/GMT-2 )",
    "id" : "Etc/GMT-2"
  }, {
    "name" : "( GMT 3:00 ) GMT+03:00( Etc/GMT-3 )",
    "id" : "Etc/GMT-3"
  }, {
    "name" : "( GMT 4:00 ) GMT+04:00( Etc/GMT-4 )",
    "id" : "Etc/GMT-4"
  }, {
    "name" : "( GMT 5:00 ) GMT+05:00( Etc/GMT-5 )",
    "id" : "Etc/GMT-5"
  }, {
    "name" : "( GMT 6:00 ) GMT+06:00( Etc/GMT-6 )",
    "id" : "Etc/GMT-6"
  }, {
    "name" : "( GMT 7:00 ) GMT+07:00( Etc/GMT-7 )",
    "id" : "Etc/GMT-7"
  }, {
    "name" : "( GMT 8:00 ) GMT+08:00( Etc/GMT-8 )",
    "id" : "Etc/GMT-8"
  }, {
    "name" : "( GMT 9:00 ) GMT+09:00( Etc/GMT-9 )",
    "id" : "Etc/GMT-9"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT0 )",
    "id" : "Etc/GMT0"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/Greenwich )",
    "id" : "Etc/Greenwich"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/UCT )",
    "id" : "Etc/UCT"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/UTC )",
    "id" : "Etc/UTC"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/Universal )",
    "id" : "Etc/Universal"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/Zulu )",
    "id" : "Etc/Zulu"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Amsterdam )",
    "id" : "Europe/Amsterdam"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Andorra )",
    "id" : "Europe/Andorra"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Athens )",
    "id" : "Europe/Athens"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Belfast )",
    "id" : "Europe/Belfast"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Belgrade )",
    "id" : "Europe/Belgrade"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Berlin )",
    "id" : "Europe/Berlin"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Bratislava )",
    "id" : "Europe/Bratislava"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Brussels )",
    "id" : "Europe/Brussels"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Bucharest )",
    "id" : "Europe/Bucharest"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Budapest )",
    "id" : "Europe/Budapest"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Busingen )",
    "id" : "Europe/Busingen"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Chisinau )",
    "id" : "Europe/Chisinau"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Copenhagen )",
    "id" : "Europe/Copenhagen"
  }, {
    "name" : "( GMT 1:00 ) Irish Summer Time( Europe/Dublin )",
    "id" : "Europe/Dublin"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Gibraltar )",
    "id" : "Europe/Gibraltar"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Guernsey )",
    "id" : "Europe/Guernsey"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Helsinki )",
    "id" : "Europe/Helsinki"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Isle_of_Man )",
    "id" : "Europe/Isle_of_Man"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Istanbul )",
    "id" : "Europe/Istanbul"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Jersey )",
    "id" : "Europe/Jersey"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Time( Europe/Kaliningrad )",
    "id" : "Europe/Kaliningrad"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Kiev )",
    "id" : "Europe/Kiev"
  }, {
    "name" : "( GMT 1:00 ) Western European Summer Time( Europe/Lisbon )",
    "id" : "Europe/Lisbon"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Ljubljana )",
    "id" : "Europe/Ljubljana"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/London )",
    "id" : "Europe/London"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Luxembourg )",
    "id" : "Europe/Luxembourg"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Madrid )",
    "id" : "Europe/Madrid"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Malta )",
    "id" : "Europe/Malta"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Mariehamn )",
    "id" : "Europe/Mariehamn"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Minsk )",
    "id" : "Europe/Minsk"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Monaco )",
    "id" : "Europe/Monaco"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Moscow )",
    "id" : "Europe/Moscow"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Nicosia )",
    "id" : "Europe/Nicosia"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Oslo )",
    "id" : "Europe/Oslo"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Paris )",
    "id" : "Europe/Paris"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Podgorica )",
    "id" : "Europe/Podgorica"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Prague )",
    "id" : "Europe/Prague"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Riga )",
    "id" : "Europe/Riga"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Rome )",
    "id" : "Europe/Rome"
  }, {
    "name" : "( GMT 4:00 ) Samara Time( Europe/Samara )",
    "id" : "Europe/Samara"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/San_Marino )",
    "id" : "Europe/San_Marino"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Sarajevo )",
    "id" : "Europe/Sarajevo"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Simferopol )",
    "id" : "Europe/Simferopol"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Skopje )",
    "id" : "Europe/Skopje"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Sofia )",
    "id" : "Europe/Sofia"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Stockholm )",
    "id" : "Europe/Stockholm"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Tallinn )",
    "id" : "Europe/Tallinn"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Tirane )",
    "id" : "Europe/Tirane"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Tiraspol )",
    "id" : "Europe/Tiraspol"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Uzhgorod )",
    "id" : "Europe/Uzhgorod"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vaduz )",
    "id" : "Europe/Vaduz"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vatican )",
    "id" : "Europe/Vatican"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vienna )",
    "id" : "Europe/Vienna"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Vilnius )",
    "id" : "Europe/Vilnius"
  }, {
    "name" : "( GMT 4:00 ) Moscow Standard Time( Europe/Volgograd )",
    "id" : "Europe/Volgograd"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Warsaw )",
    "id" : "Europe/Warsaw"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Zagreb )",
    "id" : "Europe/Zagreb"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Zaporozhye )",
    "id" : "Europe/Zaporozhye"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Zurich )",
    "id" : "Europe/Zurich"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( GB )",
    "id" : "GB"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( GB-Eire )",
    "id" : "GB-Eire"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
    "id" : "GMT"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT0 )",
    "id" : "GMT0"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Greenwich )",
    "id" : "Greenwich"
  }, {
    "name" : "( GMT 8:00 ) Hong Kong Time( Hongkong )",
    "id" : "Hongkong"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Iceland )",
    "id" : "Iceland"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Antananarivo )",
    "id" : "Indian/Antananarivo"
  }, {
    "name" : "( GMT 5:00 ) Indian Ocean Territory Time( Indian/Chagos )",
    "id" : "Indian/Chagos"
  }, {
    "name" : "( GMT 7:00 ) Christmas Island Time( Indian/Christmas )",
    "id" : "Indian/Christmas"
  }, {
    "name" : "( GMT 6:30 ) Cocos Islands Time( Indian/Cocos )",
    "id" : "Indian/Cocos"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Comoro )",
    "id" : "Indian/Comoro"
  }, {
    "name" : "( GMT 5:00 ) French Southern & Antarctic Lands Time( Indian/Kerguelen )",
    "id" : "Indian/Kerguelen"
  }, {
    "name" : "( GMT 4:00 ) Seychelles Time( Indian/Mahe )",
    "id" : "Indian/Mahe"
  }, {
    "name" : "( GMT 5:00 ) Maldives Time( Indian/Maldives )",
    "id" : "Indian/Maldives"
  }, {
    "name" : "( GMT 4:00 ) Mauritius Time( Indian/Mauritius )",
    "id" : "Indian/Mauritius"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Mayotte )",
    "id" : "Indian/Mayotte"
  }, {
    "name" : "( GMT 4:00 ) Reunion Time( Indian/Reunion )",
    "id" : "Indian/Reunion"
  }, {
    "name" : "( GMT 3:30 ) Iran Daylight Time( Iran )",
    "id" : "Iran"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Israel )",
    "id" : "Israel"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( Jamaica )",
    "id" : "Jamaica"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( Japan )",
    "id" : "Japan"
  }, {
    "name" : "( GMT -12:00 ) Marshall Islands Time( Kwajalein )",
    "id" : "Kwajalein"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Libya )",
    "id" : "Libya"
  }, {
    "name" : "( GMT 1:00 ) Middle Europe Summer Time( MET )",
    "id" : "MET"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( MST7MDT )",
    "id" : "MST7MDT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Mexico/BajaNorte )",
    "id" : "Mexico/BajaNorte"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( Mexico/BajaSur )",
    "id" : "Mexico/BajaSur"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( Mexico/General )",
    "id" : "Mexico/General"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( NZ )",
    "id" : "NZ"
  }, {
    "name" : "( GMT 12:45 ) Chatham Daylight Time( NZ-CHAT )",
    "id" : "NZ-CHAT"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( Navajo )",
    "id" : "Navajo"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( PRC )",
    "id" : "PRC"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( PST8PDT )",
    "id" : "PST8PDT"
  }, {
    "name" : "( GMT -11:00 ) West Samoa Daylight Time( Pacific/Apia )",
    "id" : "Pacific/Apia"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Pacific/Auckland )",
    "id" : "Pacific/Auckland"
  }, {
    "name" : "( GMT 11:00 ) Bougainville Standard Time( Pacific/Bougainville )",
    "id" : "Pacific/Bougainville"
  }, {
    "name" : "( GMT 12:45 ) Chatham Daylight Time( Pacific/Chatham )",
    "id" : "Pacific/Chatham"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Chuuk )",
    "id" : "Pacific/Chuuk"
  }, {
    "name" : "( GMT -6:00 ) Easter Is. Time( Pacific/Easter )",
    "id" : "Pacific/Easter"
  }, {
    "name" : "( GMT 11:00 ) Vanuatu Time( Pacific/Efate )",
    "id" : "Pacific/Efate"
  }, {
    "name" : "( GMT -12:00 ) Phoenix Is. Time( Pacific/Enderbury )",
    "id" : "Pacific/Enderbury"
  }, {
    "name" : "( GMT -10:00 ) Tokelau Time( Pacific/Fakaofo )",
    "id" : "Pacific/Fakaofo"
  }, {
    "name" : "( GMT 12:00 ) Fiji Summer Time( Pacific/Fiji )",
    "id" : "Pacific/Fiji"
  }, {
    "name" : "( GMT 12:00 ) Tuvalu Time( Pacific/Funafuti )",
    "id" : "Pacific/Funafuti"
  }, {
    "name" : "( GMT -5:00 ) Galapagos Time( Pacific/Galapagos )",
    "id" : "Pacific/Galapagos"
  }, {
    "name" : "( GMT -9:00 ) Gambier Time( Pacific/Gambier )",
    "id" : "Pacific/Gambier"
  }, {
    "name" : "( GMT 11:00 ) Solomon Is. Time( Pacific/Guadalcanal )",
    "id" : "Pacific/Guadalcanal"
  }, {
    "name" : "( GMT 10:00 ) Chamorro Standard Time( Pacific/Guam )",
    "id" : "Pacific/Guam"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( Pacific/Honolulu )",
    "id" : "Pacific/Honolulu"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( Pacific/Johnston )",
    "id" : "Pacific/Johnston"
  }, {
    "name" : "( GMT -10:40 ) Line Is. Time( Pacific/Kiritimati )",
    "id" : "Pacific/Kiritimati"
  }, {
    "name" : "( GMT 12:00 ) Kosrae Time( Pacific/Kosrae )",
    "id" : "Pacific/Kosrae"
  }, {
    "name" : "( GMT -12:00 ) Marshall Islands Time( Pacific/Kwajalein )",
    "id" : "Pacific/Kwajalein"
  }, {
    "name" : "( GMT 12:00 ) Marshall Islands Time( Pacific/Majuro )",
    "id" : "Pacific/Majuro"
  }, {
    "name" : "( GMT -9:30 ) Marquesas Time( Pacific/Marquesas )",
    "id" : "Pacific/Marquesas"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Midway )",
    "id" : "Pacific/Midway"
  }, {
    "name" : "( GMT 11:30 ) Nauru Time( Pacific/Nauru )",
    "id" : "Pacific/Nauru"
  }, {
    "name" : "( GMT -11:30 ) Niue Time( Pacific/Niue )",
    "id" : "Pacific/Niue"
  }, {
    "name" : "( GMT 11:30 ) Norfolk Time( Pacific/Norfolk )",
    "id" : "Pacific/Norfolk"
  }, {
    "name" : "( GMT 11:00 ) New Caledonia Time( Pacific/Noumea )",
    "id" : "Pacific/Noumea"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Pago_Pago )",
    "id" : "Pacific/Pago_Pago"
  }, {
    "name" : "( GMT 9:00 ) Palau Time( Pacific/Palau )",
    "id" : "Pacific/Palau"
  }, {
    "name" : "( GMT -8:30 ) Pitcairn Standard Time( Pacific/Pitcairn )",
    "id" : "Pacific/Pitcairn"
  }, {
    "name" : "( GMT 11:00 ) Pohnpei Time( Pacific/Pohnpei )",
    "id" : "Pacific/Pohnpei"
  }, {
    "name" : "( GMT 11:00 ) Pohnpei Time( Pacific/Ponape )",
    "id" : "Pacific/Ponape"
  }, {
    "name" : "( GMT 10:00 ) Papua New Guinea Time( Pacific/Port_Moresby )",
    "id" : "Pacific/Port_Moresby"
  }, {
    "name" : "( GMT -10:30 ) Cook Is. Time( Pacific/Rarotonga )",
    "id" : "Pacific/Rarotonga"
  }, {
    "name" : "( GMT 10:00 ) Chamorro Standard Time( Pacific/Saipan )",
    "id" : "Pacific/Saipan"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Samoa )",
    "id" : "Pacific/Samoa"
  }, {
    "name" : "( GMT -10:00 ) Tahiti Time( Pacific/Tahiti )",
    "id" : "Pacific/Tahiti"
  }, {
    "name" : "( GMT 12:00 ) Gilbert Is. Time( Pacific/Tarawa )",
    "id" : "Pacific/Tarawa"
  }, {
    "name" : "( GMT 13:00 ) Tonga Time( Pacific/Tongatapu )",
    "id" : "Pacific/Tongatapu"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Truk )",
    "id" : "Pacific/Truk"
  }, {
    "name" : "( GMT 12:00 ) Wake Time( Pacific/Wake )",
    "id" : "Pacific/Wake"
  }, {
    "name" : "( GMT 12:00 ) Wallis & Futuna Time( Pacific/Wallis )",
    "id" : "Pacific/Wallis"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Yap )",
    "id" : "Pacific/Yap"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Poland )",
    "id" : "Poland"
  }, {
    "name" : "( GMT 1:00 ) Western European Summer Time( Portugal )",
    "id" : "Portugal"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( ROK )",
    "id" : "ROK"
  }, {
    "name" : "( GMT 7:30 ) Singapore Time( Singapore )",
    "id" : "Singapore"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( SystemV/AST4 )",
    "id" : "SystemV/AST4"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( SystemV/AST4ADT )",
    "id" : "SystemV/AST4ADT"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( SystemV/CST6 )",
    "id" : "SystemV/CST6"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( SystemV/CST6CDT )",
    "id" : "SystemV/CST6CDT"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( SystemV/EST5 )",
    "id" : "SystemV/EST5"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( SystemV/EST5EDT )",
    "id" : "SystemV/EST5EDT"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( SystemV/HST10 )",
    "id" : "SystemV/HST10"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( SystemV/MST7 )",
    "id" : "SystemV/MST7"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( SystemV/MST7MDT )",
    "id" : "SystemV/MST7MDT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Standard Time( SystemV/PST8 )",
    "id" : "SystemV/PST8"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( SystemV/PST8PDT )",
    "id" : "SystemV/PST8PDT"
  }, {
    "name" : "( GMT -9:00 ) Alaska Standard Time( SystemV/YST9 )",
    "id" : "SystemV/YST9"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( SystemV/YST9YDT )",
    "id" : "SystemV/YST9YDT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Turkey )",
    "id" : "Turkey"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( UCT )",
    "id" : "UCT"
  }, {
    "name" : "( GMT -10:00 ) Alaska Daylight Time( US/Alaska )",
    "id" : "US/Alaska"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( US/Aleutian )",
    "id" : "US/Aleutian"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( US/Arizona )",
    "id" : "US/Arizona"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( US/Central )",
    "id" : "US/Central"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/East-Indiana )",
    "id" : "US/East-Indiana"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/Eastern )",
    "id" : "US/Eastern"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( US/Hawaii )",
    "id" : "US/Hawaii"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( US/Indiana-Starke )",
    "id" : "US/Indiana-Starke"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/Michigan )",
    "id" : "US/Michigan"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( US/Mountain )",
    "id" : "US/Mountain"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( US/Pacific )",
    "id" : "US/Pacific"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( US/Pacific-New )",
    "id" : "US/Pacific-New"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( US/Samoa )",
    "id" : "US/Samoa"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( UTC )",
    "id" : "UTC"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Universal )",
    "id" : "Universal"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( W-SU )",
    "id" : "W-SU"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( WET )",
    "id" : "WET"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Zulu )",
    "id" : "Zulu"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( EST )",
    "id" : "EST"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( HST )",
    "id" : "HST"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( MST )",
    "id" : "MST"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( ACT )",
    "id" : "ACT"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( AET )",
    "id" : "AET"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( AGT )",
    "id" : "AGT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( ART )",
    "id" : "ART"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( AST )",
    "id" : "AST"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( BET )",
    "id" : "BET"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( BST )",
    "id" : "BST"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( CAT )",
    "id" : "CAT"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( CNT )",
    "id" : "CNT"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( CST )",
    "id" : "CST"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( CTT )",
    "id" : "CTT"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( EAT )",
    "id" : "EAT"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( ECT )",
    "id" : "ECT"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( IET )",
    "id" : "IET"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( IST )",
    "id" : "IST"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( JST )",
    "id" : "JST"
  }, {
    "name" : "( GMT 13:00 ) West Samoa Daylight Time( MIT )",
    "id" : "MIT"
  }, {
    "name" : "( GMT 4:00 ) Armenia Time( NET )",
    "id" : "NET"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( NST )",
    "id" : "NST"
  }, {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( PNT )",
    "id" : "PNT"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( PRT )",
    "id" : "PRT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( PST )",
    "id" : "PST"
  }, {
    "name" : "( GMT 11:00 ) Solomon Is. Time( SST )",
    "id" : "SST"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( VST )",
    "id" : "VST"
  } ]
}

Agent Signatures

Signature refers to the self-identifying/self-referencing details that agents include at the end of their responses to customers.

ATTRIBUTES

Attribute Name

Data Type

Description

isActive

boolean

Status of the signature

~~agentId~~

deprecated

long

ID of the agent. This key is deprecated, Please use id key instead of this

long

ID of the agent

defaultSignature

string

Default signature of the agent

customizedSignatures

show Attributes

list

Department-specific, customized signatures of the agent

Example

{ "customizedSignatures" : [ { "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales & Marketing</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>", "departmentId" : 4000000015063 }, { "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>User Onboarding</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div></div><div><br /></div></div>", "departmentId" : 4000000027042 } ], "agentId" : 4000000012902, "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div></div><div><br /></div></div>", "id" : "4000000012902", "isActive" : true }

Get signatures of agent

This API fetches the different signatures configured by an agent.

GET /api/v1/agents/{agent_id}/signatures

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000012902/signatures
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  }, {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>User Onboarding</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div></div><div><br /></div></div>",
    "departmentId" : 4000000027042
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Update signatures of agent

This API updates the existing signatures of an agent.

Attributes

Param Name

Data Type

Description

isActive

boolean

optional

Status of the signature

defaultSignature

string

optional,
max chars : 65000

Default signature of the agent

customizedSignatures

list

optional

Department-specific, customized signatures of the agent

PATCH /api/v1/agents/{agent_id}/signatures

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/agents/4000000012902/signatures
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>"
}'

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Update customized signatures of agent

This API updates the customized signatures of an agent.

Attributes

Param Name

Data Type

Description

departmentId

long

required

ID of the department in which the signature exists

signature

string

required,
max chars : 65000

Signature of the agent in that department

POST /api/v1/agents/{agent_id}/updateCustomizedSignature

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/4000000012902/updateCustomizedSignature
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div>Sales &amp; Marketing<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
  "departmentId" : 4000000015063
}'

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div>Sales &amp; Marketing<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Businesshours

Business hours are the working hours of your help desk. In Zoho Desk, you can configure multiple business hour sets, based on factors, such as the shift times of your agents, and time zones of the regions you cater to. Defining business hours is important because the due time for responding to and resolving tickets are calculated based on these hours. They play a critical role in time tracking and SLAs

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the business hours set

status

String

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

String

Type of the business hours set. Values allowed are 24X7 (available anytime throughout the week), SPECIFIC (available during specific hours on the days selected),and CUSTOM (available during different hours on different days

holidayListId

long

ID of the holiday list to associate with the business hours set

timeZoneId

string

ID of the time zone to associate with the business hours set

businessTimes

show Attributes

list

Business hours for the week

Example

{ "modifiedTime" : "2018-12-03T07:16:59.198Z", "createdBy" : "4000000016079", "associatedHolidayList" : { "holidayListStatus" : "INACTIVE", "holidayListId" : "4000000105030", "holidayListName" : "General HolidayList" }, "name" : "UK Shift BusinessHours", "businessTimes" : [ { "startTime" : "09:00", "endTime" : "18:00", "day" : "MONDAY" }, { "startTime" : "09:00", "endTime" : "18:00", "day" : "TUESDAY" }, { "startTime" : "09:00", "endTime" : "18:00", "day" : "WEDNESDAY" }, { "startTime" : "09:00", "endTime" : "18:00", "day" : "THURSDAY" }, { "startTime" : "09:00", "endTime" : "18:00", "day" : "FRIDAY" }, { "startTime" : "09:00", "endTime" : "18:00", "day" : "SATURDAY" }, { "startTime" : "00:00", "endTime" : "00:00", "day" : "SUNDAY" } ], "timeZone" : { "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )", "id" : "GMT" }, "createdTime" : "2018-11-28T11:25:45.082Z", "modifiedBy" : "4000000016079", "id" : "4000000101009", "type" : "CUSTOM", "status" : "INACTIVE" }

Create business hours set

This API creates a business hours set in your help desk portal

Attributes

Param Name

Data Type

Description

name

String

required

Name of the business hours set

status

String

required

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

String

required

holidayListId

long

optional

ID of the holiday list to associate with the business hours set

timeZoneId

string

optional,
max chars : 100

ID of the time zone to associate with the business hours set

businessTimes

list

optional

Business hours for the week

POST /api/v1/businessHours

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/businessHours
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "timeZoneId" : "PLT",
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  } ],
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T07:18:39.796Z",
  "createdBy" : "4000000016079",
  "associatedHolidayList" : null,
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Get business hours set

This API fetches the details of a business hours set configured in your help desk portal

GET /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/businessHours/4000000186010
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-12-10T07:18:39.796Z",
  "createdBy" : "4000000016079",
  "associatedHolidayList" : null,
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Update business hours set

TThis API updates the details of a business hours set configured in your help desk portal

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the business hours set

status

String

optional

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

String

optional

holidayListId

long

optional

ID of the holiday list to associate with the business hours set

timeZoneId

string

optional,
max chars : 100

ID of the time zone to associate with the business hours set

businessTimes

list

optional

Business hours for the week

PATCH /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/businessHours/6000000045001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "holidayListId" : "4000000105030"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T09:46:28.750Z",
  "createdBy" : "4000000016079",
  "associatedHolidayList" : {
    "holidayListStatus" : "INACTIVE",
    "holidayListId" : "4000000105030",
    "holidayListName" : "General HolidayList"
  },
  "name" : "BusinssHour Pakistan Shift-with Holidays",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Delete business hours set

This API deletes a business hours set from your help desk portal

DELETE /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/businessHours/6000000033001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List business hour sets

This API lists a particular number of business hour sets, based on the limit specified

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the business hour sets must be listed

limit

integer

optional,
range : 1-50

Number of business hour sets to list

status

String

optional

Activation status of the business hour sets. Values allowed are ACTIVE and INACTIVE

GET /api/v1/businessHours

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/businessHours
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-12-10T07:09:51.265Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "BusinssHour Pak Shift",
    "businessTimes" : [ {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
      "id" : "PLT"
    },
    "createdTime" : "2018-12-10T07:09:51.265Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000185071",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T10:44:24.258Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "Specific BH",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101003",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T06:48:44.595Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000117001",
      "holidayListName" : "Overlapping Holidays"
    },
    "name" : "24X7 BusinessHour",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000103001",
    "type" : "24X7",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "Indian Shift 2",
    "businessTimes" : [ {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T12:36:11.781Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000104068",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000105030",
      "holidayListName" : "General HolidayList"
    },
    "name" : "UK 24X7 Shift",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101005",
    "type" : "24X7",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000105030",
      "holidayListName" : "General HolidayList"
    },
    "name" : "UK Shift",
    "businessTimes" : [ {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101009",
    "type" : "CUSTOM",
    "status" : "INACTIVE"
  } ]
}

List associated automation rules

This API lists a particular number of automation rules that include a business hours set,based on the limit specified

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the rules must be listed

limit

integer

optional,
range : 1-50

Number of rules to list

GET /api/v1/businessHours/{businessHourId}/relatedRules

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/businessHours/10000000317019/relatedRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ruleType" : "SUPERVISE",
    "ruleName" : "TBA1",
    "ruleId" : "6000000019012"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Priority-based SLAs",
    "ruleId" : "6000000013508"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Bronze SLAs",
    "ruleId" : "6000000013514"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Default Blueprint",
    "ruleId" : "6000000016083"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "BH BP",
    "ruleId" : "6000000018143"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Third Bp",
    "ruleId" : "6000000023018"
  } ]
}

Blueprints

Blueprints define the entire business process model that ensures your data is streamlined and adhere to your team's work style

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the blueprint

description

String

Description of blueprint

active

Boolean

Active Status of blueprint

module

String

Module of the Blueprint

departmentId

Long

Department of the Blueprint

layoutId

Long

Layout of Blueprint

type

String

Type of blueprint

Example

{ "chartData" : { "canvasPosition" : { "top" : -29, "left" : -127 }, "connectionDetails" : [ { "toUuid" : "Closed2", "transName" : "Check3", "isCommTrans" : true, "fromUuid" : "Escalated1", "usedStates" : [ "On Hold", "Open" ], "isAuto" : false }, { "toUuid" : "Closed3", "transName" : "Check3", "isCommTrans" : false, "fromUuid" : "OnHold2", "isAuto" : false }, { "toUuid" : "OnHold3", "transName" : "Check3", "isCommTrans" : false, "fromUuid" : "Open2", "isAuto" : false } ], "stateDetails" : [ { "stateName" : "Closed", "position" : { "top" : 316, "left" : 225 } }, { "stateName" : "Escalated", "position" : { "top" : 316, "left" : 225 } }, { "stateName" : "Open", "position" : { "top" : 316, "left" : 225 } } ] }, "criteria" : { "fieldConditions" : [ { "condition" : "is open", "fieldName" : "Status", "fieldModule" : "tickets", "value" : [ "${OPEN}" ] } ], "pattern" : "(1)" }, "departmentId" : "4000000007235", "module" : "Cases", "name" : "Private Threading Handling", "description" : "Automates Private Threading Handling", "type" : "NON_CONTINUOUS/CONTINUOUS", "transitions" : [ { "isAutoTransition" : false, "before" : { "accessors" : { "owners" : { "agentIds" : [ 4000000009158 ], "otherRecpts" : [ "RECORD_OWNER" ], "teamIds" : [ 4000000009158 ] }, "sharedDeptAccessors" : [ { "accessors" : { "agentIds" : [ 4000000009158 ], "teamIds" : [ 4000000009158 ] }, "deptId" : 4000000009158, "sharingType" : "READ_ONLY" } ] }, "criteriaDetails" : { "criteria" : { "fieldConditions" : [ { "condition" : "is open", "fieldName" : "Status", "value" : [ "${OPEN}" ] } ], "pattern" : "(1)" } } }, "name" : "Feedbacks need to be monitored", "description" : "Lack of instruments to repair", "during" : [ { "message" : "Add comment here" }, { "fieldUpdates" : { "criteria" : { "fieldConditions" : [ { "condition" : "is open", "fieldName" : "Status", "value" : [ "${OPEN}" ] } ], "pattern" : "(1)" }, "fieldId" : 4000000009158, "errorMsg" : "Enter a valid Priority" }, "isMandatory" : true }, { "otherActions" : "REPLY/BUG/COMMENT/RESOLUTION/APPROVAL/ATTACHMENT", "isMandatory" : false }, { "otherActions" : "COMMENT", "isMandatory" : true } ], "after" : { "fieldUpdate" : { "ids" : [ 4000000307007 ] }, "task" : { "ids" : [ 4000000307007 ] }, "customFunction" : { "ids" : [ 4000000307007 ] }, "alert" : { "ids" : [ 4000000307007 ] } }, "autoTransitionActions" : { "feedback" : "SURVEY_ALL/SURVEY_GOOD/SURVEY_AVG/SURVEY_BAD", "reply" : "REPLY_ALL/REPLY_PRIVATE/REPLY_PUBLIC" }, "isCommonTransition" : false }, { "isAutoTransition" : false, "before" : { "accessors" : { "owners" : { "agentIds" : [ 4000000009158 ], "otherRecpts" : [ "RECORD_OWNER" ], "teamIds" : [ 4000000009158 ] }, "sharedDeptAccessors" : [ { "accessors" : { "agentIds" : [ 4000000009158 ], "teamIds" : [ 4000000009158 ] }, "deptId" : 4000000009158, "sharingType" : "READ_ONLY" } ] }, "criteriaDetails" : { "criteria" : { "fieldConditions" : [ { "condition" : "is open", "fieldName" : "Status", "value" : [ "${OPEN}" ] } ], "pattern" : "(1)" } } }, "name" : "Common Handling", "description" : "Its common transition", "commonStates" : [ "Open" ], "during" : [ { "message" : "Add comment here" }, { "fieldUpdates" : { "criteria" : { "fieldConditions" : [ { "condition" : "is open", "fieldName" : "Status", "value" : [ "${OPEN}" ] } ], "pattern" : "(1)" }, "fieldId" : 4000000009158, "errorMsg" : "Enter a valid Priority" }, "isMandatory" : true }, { "otherActions" : "BUG", "isMandatory" : false }, { "otherActions" : "COMMENT", "isMandatory" : true } ], "after" : { "fieldUpdate" : { "ids" : [ 4000000307007 ] }, "task" : { "ids" : [ 4000000307007 ] }, "customFunction" : { "ids" : [ 4000000307007 ] }, "alert" : { "ids" : [ 4000000307007 ] } }, "autoTransitionActions" : { "feedback" : "SURVEY_ALL", "reply" : "REPLY_ALL" }, "isCommonTransition" : true } ], "layoutId" : 4000000007723, "connections" : [ { "fromState" : "Escalated", "toState" : "Closed", "transition" : [ "Common Handling" ] }, { "fromState" : "Escalated", "toState" : "Closed", "transition" : [ "Common Handling" ] } ], "fieldId" : 4000000000377, "states" : [ { "timeInMins" : 90, "escalations" : [ { "escalationRecipients" : { "agentIds" : [ 4000000009158 ], "otherRecpts" : [ "RECORD_OWNER" ] }, "templateId" : 4000000007355, "escalationLevel" : 1, "whenToEscalate" : 15 } ], "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ], "businessHrId" : 4000000007355, "name" : "Open", "type" : "START/INTERMEDIATE/END" }, { "timeInMins" : 30, "name" : "Escalated", "type" : "INTERMEDIATE" }, { "timeInMins" : 30, "name" : "Closed", "type" : "END" } ] }

Get Blueprint Details

To get a specific blueprint details

GET /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://support.zoho.com/api/v1/blueprints/4000000019017
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

List all blueprints in a department

To get all blueprints in a specific department

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Department for which the blueprints are listed

module

String

required

module of the blueprints to be listed

status

String

optional

To get blueprints by status, allowed values are ACTIVE and INACTIVE

GET /api/v1/blueprints

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://support.zoho.com/api/v1/blueprints?departmentId=4000000007245
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-05-04 08:07:57.0",
    "orderNumber" : "3",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "Issue fixed",
      "id" : "1000000309105"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Open",
      "id" : 1000000309101
    }, {
      "name" : "Closed",
      "id" : 1000000309119
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Automate QA process",
    "createdTime" : "2018-05-02 13:39:30.0",
    "id" : "1000000309097",
    "connections" : [ {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000309101"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000309119"
      },
      "transitions" : [ {
        "name" : "Issue fixed",
        "id" : "1000000309105"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-04-24 05:53:28.0",
    "orderNumber" : "4",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "before",
      "id" : "1000000232199"
    }, {
      "name" : "after",
      "id" : "1000000232197"
    }, {
      "name" : "during",
      "id" : "1000000232201"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Closed",
      "id" : 1000000232189
    }, {
      "name" : "On Hold",
      "id" : 1000000232191
    }, {
      "name" : "Open",
      "id" : 1000000232193
    }, {
      "name" : "Escalated",
      "id" : 1000000232195
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "AUtomate HR process",
    "createdTime" : "2018-04-10 15:43:54.0",
    "id" : "1000000232187",
    "connections" : [ {
      "fromState" : {
        "name" : "On Hold",
        "id" : "1000000232191"
      },
      "toState" : {
        "name" : "Escalated",
        "id" : "1000000232195"
      },
      "transitions" : [ {
        "name" : "before",
        "id" : "1000000232199"
      } ]
    }, {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000232193"
      },
      "toState" : {
        "name" : "On Hold",
        "id" : "1000000232191"
      },
      "transitions" : [ {
        "name" : "after",
        "id" : "1000000232197"
      } ]
    }, {
      "fromState" : {
        "name" : "Escalated",
        "id" : "1000000232195"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000232189"
      },
      "transitions" : [ {
        "name" : "during",
        "id" : "1000000232201"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-04-03 13:34:08.0",
    "orderNumber" : "5",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "to onhold",
      "id" : "1000000173011"
    }, {
      "name" : "To close",
      "id" : "1000000173009"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Closed",
      "id" : 1000000173003
    }, {
      "name" : "Open",
      "id" : 1000000173005
    }, {
      "name" : "On Hold",
      "id" : 1000000173007
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Shipping process",
    "createdTime" : "2018-03-28 12:29:11.0",
    "id" : "1000000173001",
    "connections" : [ {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000173005"
      },
      "toState" : {
        "name" : "On Hold",
        "id" : "1000000173007"
      },
      "transitions" : [ {
        "name" : "to onhold",
        "id" : "1000000173011"
      } ]
    }, {
      "fromState" : {
        "name" : "On Hold",
        "id" : "1000000173007"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000173003"
      },
      "transitions" : [ {
        "name" : "To close",
        "id" : "1000000173009"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-05-03 13:18:24.0",
    "orderNumber" : "5",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "t1",
      "id" : "1000000313281"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Approval 2",
      "id" : 1000000313277
    }, {
      "name" : "Approval 2 approved",
      "id" : 1000000313279
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Ticket Support process",
    "createdTime" : "2018-05-03 13:18:24.0",
    "id" : "1000000313275",
    "connections" : [ {
      "fromState" : {
        "name" : "Approval 2 approved",
        "id" : "1000000313279"
      },
      "toState" : {
        "name" : "Approval 2",
        "id" : "1000000313277"
      },
      "transitions" : [ {
        "name" : "t1",
        "id" : "1000000313281"
      } ]
    } ],
    "fieldId" : "1000000000506"
  } ]
}

Create Blueprint

To create a blueprint

Attributes

Param Name

Data Type

Description

name

String

required

Name of the blueprint

description

String

optional

Description of blueprint

active

Boolean

optional

Active Status of blueprint

module

String

required

Module of the Blueprint

departmentId

Long

required

Department of the Blueprint

layoutId

Long

required

Layout of Blueprint

type

String

required

Type of blueprint

fieldId

Long

required

Field mapped for Blueprint

criteria

list

optional

The criteria details for the blueprint

chartData

show Attributes

object

required

Blueprint Chart Data

states

list

required

State Details

transitions

list

required

Transition Details

connections

list

required

Transition Connections

POST /api/v1/blueprints

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/blueprints
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "stateName" : "Closed",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Escalated",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Open",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "name" : "Private Threading Handling",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "connections" : [ {
    "fromState" : "Open",
    "toState" : "Escalated",
    "transition" : [ "Common Handling" ]
  }, {
    "fromState" : "Escalated",
    "toState" : "Closed",
    "transition" : [ "Common Handling" ]
  } ],
  "fieldId" : 4000000000377,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "type" : "END"
  } ]
}'

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

Update a blueprint

To update an existing blueprint

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the blueprint

description

String

optional

Description of blueprint

active

Boolean

optional

Active Status of blueprint

module

String

optional

Module of the Blueprint

departmentId

Long

optional

Department of the Blueprint

layoutId

Long

optional

Layout of Blueprint

type

String

optional

Type of blueprint

fieldId

Long

optional

Field mapped for Blueprint

criteria

list

optional

The criteria details for the blueprint

chartData

show Attributes

object

optional

Blueprint Chart Data

states

list

optional

State Details

transitions

list

optional

Transition Details

connections

list

optional

Transition Connections

PATCH /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/blueprints/4000000019017
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "type" : "NON_CONTINUOUS"
}'

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

Delete Blueprint

To delete a specific blueprint

DELETE /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://support.zoho.com/api/v1/blueprints/4000000019017
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Reorder blueprints

To reorder blueprints in a specific department

Query Params

Param Name

Data Type

Description

departmentId

long

required

Department for which blueprints have to be reordered

module

String

required

module for which blueprints have to be reordered

Attributes

Param Name

Data Type

Description

ids

list

required

Blueprint Ids

POST /api/v1/blueprints/reorder

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/blueprints/reorder?departmentId=4000000007245
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'[ "4000000019017", "4000000019019", "4000000019023", "4000000019021" ]'

Response Example

Get Applied Blueprint details of ticket for an user

To get the applied blueprint details of a ticket

Query Params

Param Name

Data Type

Description

include
see documentation

string

optional,
max chars : 100

Meta information related to the transition owners. Values allowed are: transitionOwnerAgents, transitionOwnerTeams, transitionOwnerDept to include agents,teams,department under owners. You can pass multiple values by separating them with commas in the API request.

GET /api/v1/tickets/{ticket_id}/blueprint

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://support.zoho.com/api/v1/tickets/4000000159817/blueprint
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "name" : "Automate QA Process",
  "id" : 1000000087001,
  "state" : {
    "dueDate" : "2018-02-27T20:49:00.000Z",
    "id" : "1000000087003",
    "type" : "START"
  },
  "transitions" : [ {
    "fromState" : "Open",
    "toState" : "Escalated",
    "criteria" : {
      "fieldConditions" : [ {
        "condition" : "is open",
        "fieldName" : "Status",
        "value" : [ "${OPEN}" ]
      } ],
      "pattern" : "(1)"
    },
    "name" : "Escalate to developers",
    "owners" : [ {
      "agentIds" : [ "1000000012635" ],
      "teams" : [ {
        "name" : "Sales Representatives",
        "id" : "1000000012435"
      } ],
      "departmentId" : "1000000010712",
      "department" : {
        "name" : "Zylker",
        "id" : "1000000010712"
      },
      "teamIds" : [ "1000000012435" ],
      "agents" : [ {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/1000000012635/photo",
        "firstName" : "Lucas",
        "lastName" : "Carol",
        "id" : "1000000012635",
        "email" : "carol@zylker.com"
      } ]
    } ],
    "id" : "1000000087011",
    "canUserPerformTransition" : true,
    "isCriteriaSatisfied" : true
  } ]
}

Get During transition form

To get During transition form details for the given transition

GET /api/v1/tickets/{ticket_id}/transitions/{transitionId}/form

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://support.zoho.com/api/v1/tickets/4000000159817/transitions/4000000152217/form
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "formActions" : [ {
    "actionType" : "FIELD_UPDATE",
    "fieldDetails" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    },
    "isMandatory" : true
  }, {
    "actionType" : "MESSAGE",
    "content" : "Post your reply here"
  }, {
    "actionType" : "REPLY",
    "isMandatory" : true
  }, {
    "actionType" : "COMMENT",
    "isMandatory" : false
  }, {
    "actionType" : "RESOLUTION",
    "isMandatory" : true
  }, {
    "actionType" : "APPROVAL",
    "isMandatory" : true
  }, {
    "actionType" : "BUG",
    "isMandatory" : false
  }, {
    "actionType" : "ATTACHMENTS",
    "isMandatory" : true
  } ],
  "transitionId" : "4000000152217",
  "continuousTransitions" : [ {
    "transitionId" : "4000000152219",
    "transtionName" : "Close"
  }, {
    "transitionId" : "4000000152221",
    "transtionName" : "Solve"
  } ],
  "isContinuousTransition" : true
}

Revoke Blueprint at Entity Level

To revoke blueprint from an entity

POST /api/v1/tickets/{ticket_id}/revokeBlueprint

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/revokeBlueprint
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "message" : "Blueprint has been revoked from this ticket"
}

Revoke Blueprint from Blueprint Level

To revoke all entities from a particular blueprint

POST /api/v1/blueprints/([0-9]+)/revoke

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/blueprints/4000000159817/revoke
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "message" : "Blueprint revoke scheduled"
}

Validate transition field updates

To validate field updates for the given transition

Attributes

Param Name

Data Type

Description

customFields

object

optional

null

cleartextpattern

string

optional,
max chars : 65535

null

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/validateFieldUpdates

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/myTransitions/4000000152217/validateFieldUpdates
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "customFields" : {
    "customEmail" : "zdesk@gmail.com"
  },
  "channel" : "Facebook",
  "priority" : "Medium",
  "assigneeId" : 1000000012635
}'

Response Example

{
  "invalidFieldUpdates" : [ {
    "fieldName" : "priority",
    "fieldId" : 4000000159817,
    "errorMsg" : "Priority can't be high"
  }, {
    "fieldName" : "customEmail",
    "fieldId" : 4000000159819,
    "errorMsg" : "Email is invalid"
  } ]
}

Perform transition

To perform transition for an entity

Attributes

Param Name

Data Type

Description

APPROVAL

JSONObject

optional

Approval details

RESOLUTION

JSONObject

optional

Resolution details

ATTACHMENT

JSONObject

optional

Attachment Details

JSONObject

optional

Reply Content details

COMMENT

JSONObject

optional

Comment Details

FIELD_UPDATE

JSONObject

optional

Fields To Update

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/perform

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/transitions/4000000152217/perform
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ATTACHMENT" : {
    "uploads" : [ {
      "isPublic" : false,
      "id" : 1000000096035
    } ]
  },
  "FIELD_UPDATE" : {
    "channel" : "Facebook"
  },
  "RESOLUTION" : {
    "toNotifyContactForResolution" : true,
    "content" : "This ticket has to be solved"
  },
  "APPROVAL" : {
    "approverIds" : [ 1000000012635 ],
    "subject" : "Has to be sent for approval"
  },
  "REPLY" : {
    "channel" : "EMAIL",
    "to" : "nancy.silvya+1@zohocorp.com",
    "isPrivate" : false,
    "fromEmailAddress" : "support@khazanacollections.localzohodesk.com",
    "contentType" : "plainText",
    "content" : "Hi I m Nancy replying.. ",
    "isForward" : false,
    "uploads" : [ 1000000096035 ]
  },
  "COMMENT" : {
    "isPublicComment" : false,
    "content" : "Comment is to test blueprint",
    "uploads" : [ 1000000096035 ]
  }
}'

Response Example

{
  "message" : "Transition has been completed"
}

Dashboards

In following APIs duration param is mapped as follows: LAST_30_DAYS, LAST_7_DAYS,THIS_WEEK,LAST_WEEK,THIS_MONTH,LAST_MONTH,CUSTOM_IN_DATE [mention start and end date in dd-mm-yyyy format],CUSTOM_IN_MILLIS [mention start and end date in milliseconds].

Get created tickets count

This API fetches the number of tickets created in a particular duration.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/createdTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/createdTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Get on hold tickets count

This API fetches the number of tickets that are in the on hold status.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/onholdTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/onholdTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Get closed tickets count

This API fetches the number of tickets that are resolved.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/solvedTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/solvedTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=channel
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "Feedback Widget",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Email",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Web",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "Phone",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Forums",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Chat",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Twitter",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Facebook",
    "referenceValue" : null
  } ],
  "avg" : "0.12",
  "groupedBy" : "channel"
}

Get unresolved tickets count

This API fetches the number of tickets that have remained unresolved over a particular period.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/backlogTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/backlogTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=agent
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "102",
  "ticketCount" : [ {
    "count" : "54",
    "value" : "Unassigned",
    "referenceValue" : null
  }, {
    "count" : "48",
    "value" : "Priyanka",
    "referenceValue" : "4000000012629"
  } ],
  "avg" : "51.0"
}

List resolution times

This API lists the durations taken to resolve tickets.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups stats according to a specific attribute: date, channel, agent, or hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/ticketsResolutionTime

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/ticketsResolutionTime?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=agent
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalAvgAgentTime" : "41:50 hrs",
  "timeData" : [ {
    "avgSystemTime" : "41:50 hrs",
    "ticketCount" : "1",
    "avgAgentTime" : "41:50 hrs",
    "value" : "Priyanka",
    "referenceValue" : "4000000012629"
  } ],
  "totalTicketCount" : "1",
  "totalAvgSystemTime" : "41:50 hrs",
  "groupedBy" : "agent"
}

List response times

This API lists the durations taken to respond to tickets.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups stats according to a specific attribute: date, channel, agent, or hour

isFirstResponse

boolean

required

Key that specifies if the response is the first response to the customer question

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/responseTime

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/responseTime?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=CUSTOM_IN_DATE&startDate=01-04-2018&endDate=10-04-2018&groupBy=channel
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalAvgAgentTime" : "41:50 hrs",
  "timeData" : [ {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Feedback Widget",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Email",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Web",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "41:50 hrs",
    "avgAgentTime" : "41:50 hrs",
    "responseCount" : "1",
    "value" : "Phone",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Forums",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Chat",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Twitter",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Facebook",
    "referenceValue" : null
  } ],
  "totalAvgSystemTime" : "41:50 hrs",
  "groupedBy" : "channel",
  "totalResponseCount" : "1"
}

Get total response count

This API fetches the total number of responses sent/made by your agents.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/responseCount

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/responseCount?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "avg" : "0.0",
  "groupedBy" : "date",
  "totalResponseCount" : "0",
  "responseCount" : [ {
    "count" : "0",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-08",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-09",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-10",
    "referenceValue" : null
  } ]
}

Get reopened tickets count

This API fetches the number of tickets that were reopened in your help desk portal.

Query Params

Param Name

Data Type

Description

groupBy

string

required,
max chars : 100

Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/reopenedTickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET http://support.zoho.com/api/v1/dashboards/reopenedTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Domain Mapping

By default, the web address of your help center is a Zoho Desk sub-domain in the "desk.zoho.com/portal/<mycompany>" format. However, you can personalize this address, so that your customers can submit their tickets from a sub-domain, such as 'support.mycompany.com'. This feature is called domain/host mapping.

ATTRIBUTES

Attribute Name

Data Type

Description

domain

string

Address of the domain

isVerified

boolean

Key that denotes if the domain is verified

isApplied

boolean

Key that denotes if the domain is applied to the portal

zdSecurityCode

string

Zoho Desk domain security code to add in the domain service provider's CNAME

verifiedTime

timestamp

Time of verifying the domain

appliedTime

timestamp

Time of applying the domain to the portal

verifiedBy

long

ID of user who verified the domain

appliedBy

long

ID of user who applied the domain to the portal

sslStatus

string

SSL status of the domain

sslRequestStatus

string

SSL request status of the domain if SSL certificate is requested for the domain

sslRequestedBy

long

ID of user who requested for the SSL certificate for the domain

sslRequestedTime

timestamp

Time of requesting the SSL certificate for the domain

Example

{ "appliedTime" : null, "sslRequestStatus" : null, "sslRequestedBy" : null, "isVerified" : false, "sslStatus" : "NO_SSL", "domain" : "support.zylker.com", "zdSecurityCode" : "zdc3b95061484994060a401652cb2a45b2", "sslRequestedTime" : null, "isApplied" : false, "appliedBy" : null, "verifiedBy" : null, "verifiedTime" : null }

Add domain

This API adds a domain to your help desk.

Attributes

Param Name

Data Type

Description

domain

string

required,
max chars : 46

Address of the domain

POST /api/v1/domains

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/domains
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : null,
  "sslRequestStatus" : null,
  "sslRequestedBy" : null,
  "isVerified" : false,
  "sslStatus" : "NO_SSL",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : "zdc3b95061484994060a401652cb2a45b2",
  "sslRequestedTime" : null,
  "isApplied" : false,
  "appliedBy" : null,
  "verifiedBy" : null,
  "verifiedTime" : null
}

Verify domain

This API verifies a domain in your help desk.

Attributes

Param Name

Data Type

Description

domain

string

required,
max chars : 100

Domain to be verified.

method

string

required,
max chars : 100

Domain verification method. CNAME or HTML.

POST /api/v1/domains/verify

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/domains/verify
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "method" : "CNAME",
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : null,
  "sslRequestStatus" : null,
  "sslRequestedBy" : null,
  "isVerified" : true,
  "sslStatus" : "NO_SSL",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : null,
  "sslRequestedTime" : null,
  "isApplied" : false,
  "appliedBy" : null,
  "verifiedBy" : "8000000012800",
  "verifiedTime" : "2018-06-03T11:21:07.912Z"
}

Apply domain

This API maps a domain to the default portal in your help desk.

Attributes

Param Name

Data Type

Description

domain

string

required,
max chars : 46

Address of the domain

POST /api/v1/domains/apply

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/domains/apply
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : "2018-06-03T11:25:07.897Z",
  "sslRequestStatus" : null,
  "sslRequestedBy" : "8000000012800",
  "isVerified" : true,
  "sslStatus" : "VALID",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : null,
  "sslRequestedTime" : "2018-06-03T11:25:07.897Z",
  "isApplied" : true,
  "appliedBy" : "8000000012800",
  "verifiedBy" : "8000000012800",
  "verifiedTime" : "2018-06-03T11:21:07.912Z"
}

Reset current domain

This API resets the current domain of the default portal in your help desk.

POST /api/v1/domains/reset

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/domains/reset
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List domains

This API lists the domains configured in your help desk.

Query Params

Param Name

Data Type

Description

isVerified

boolean

optional

Key that filters domains based on their verification status

isApplied

boolean

optional

Key that filters domains based on their application status in the help desk

GET /api/v1/domains

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/domains?isVerified=true&isApplied=false
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "supportportal.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.912Z"
  }, {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "customers.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.654Z"
  }, {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "partners.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.912Z"
  } ]
}

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/moveToTrash?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Move topic

This API moves a forum topic from one community category to another.

Attributes

Param Name

Data Type

Description

categoryId

long

required

ID of the community category

POST /api/v1/communityTopics/{id}/move

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/move?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "categoryId" : "1000000012755"
}'

Response Example

Associate tags to topic

This API associates quick access/reference tags to a forum topic.

Attributes

Param Name

Data Type

Description

tags

list

required

Tag phrases

POST /api/v1/communityTopics/{id}/associateTags

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/associateTags?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

[ {
  "name" : "tag1",
  "permalink" : "tag1"
}, {
  "name" : "tag2",
  "permalink" : "tag2"
} ]

Dissociate tags from topic

This API removes quick access/reference tags from a forum topic.

Attributes

Param Name

Data Type

Description

tags

list

required

Tag phrases

POST /api/v1/communityTopics/{id}/dissociateTags

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/dissociateTags?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

List topic followers

This API lists a particular number of users who follow a forum topic, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed.

limit

int

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/communityTopics/{id}/followers

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/followers?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

List topic participants

This API lists a particular number of users who participated in a forum topic, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/communityTopics/{id}/participants

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/participants?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

List forum topics

This API lists a particular number of forum topics, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the topics must be listed

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-25

Number of topics to list

isSticky

boolean

optional

Key that defines whether the topics to list must be sticky posts or not

unreplied

boolean

optional

Key that defines whether the topics to list must contain comments or not

type

String

optional

Type of topics to list. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

tagName

String

optional

Tag by which topics must be filtered

label

String

optional

Status label by which topics must be filtered. The value of this key varies according to the topic type. Values allowed are: NOSTATUS, NEEDMOREINFO, WORKINGONIT, ANSWERED, UNANSWERED, MAYBELATER, UNDERREVIEW, IMPLEMENTED, WILLNOTIMPLEMENT, NOTAPROBLEM, TEMPORARYFIX, ANALYZING, SOLVED, UNSOLVED, and MOSTVOTED.

GET /api/v1/communityTopics

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : null,
      "type" : "AGENT"
    },
    "latestCommentTime" : "2018-10-16T09:42:12.716Z",
    "subject" : "Topic 2",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "isVoted" : true,
    "type" : "QUESTION",
    "latestCommenter" : null,
    "isSticky" : false,
    "commentCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-2",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "latestCommentTime" : "2018-10-16T09:41:46.621Z",
    "subject" : "Topic 1",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "isVoted" : true,
    "type" : "QUESTION",
    "latestCommenter" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT"
    },
    "isSticky" : false,
    "commentCount" : "2",
    "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

Get topic

This API fetches a forum topic from the user community.

GET /api/v1/communityTopics/{id}

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "isFollowing" : false,
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "label" : "NOSTATUS",
  "isVoted" : true,
  "type" : "QUESTION",
  "isSticky" : false,
  "bestCommentId" : null,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "commentCount" : "2",
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "followersCount" : "0",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "isTicketCreated" : false
}

Get topic by permalink

This API fetches a forum topic, based on the permalink in the API request.

Query Params

Param Name

Data Type

Description

permalink

String

required

permalink of the topic

GET /api/v1/communityTopicByPermalink

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopicByPermalink?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "END_USER"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "isFollowing" : false,
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "label" : "NOSTATUS",
  "isVoted" : true,
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "commentCount" : "2",
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "followersCount" : "0",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "isTicketCreated" : false
}

Add topic

This API helps add a forum topic in the user community.

Attributes

Param Name

Data Type

Description

subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

mailTo

JSONArray

optional

Email IDs to which the topic must be sent after publishing

POST /api/v1/communityTopics

OAuth Scope

Desk.community.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "mailTo" : [ "user1@zohocorp.com" ],
  "type" : "QUESTION",
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "isFollowing" : false,
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "label" : "NOSTATUS",
  "isVoted" : true,
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "commentCount" : "2",
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "followersCount" : "0",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "isTicketCreated" : false
}

Update topic

This API helps update a published forum topic.

Attributes

Param Name

Data Type

Description

subject

String

optional

Title of the topic

content

String

optional

Body content of the topic

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

type

String

optional

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

label

String

optional

Status label of the topic. The value of this key varies according to the topic type. Values allowed are: NOSTATUS, NEEDMOREINFO, WORKINGONIT, ANSWERED, UNANSWERED, MAYBELATER, UNDERREVIEW, IMPLEMENTED, WILLNOTIMPLEMENT, NOTAPROBLEM, TEMPORARYFIX, ANALYZING, SOLVED, UNSOLVED, and MOSTVOTED.

PATCH /api/v1/communityTopics/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>"
}'

Response Example

{
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : null,
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "isFollowing" : false,
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "label" : "NOSTATUS",
  "isVoted" : true,
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "commentCount" : "2",
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "followersCount" : "0",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "isTicketCreated" : false
}

Add comment

This API helps add a comment to a forum topic.

Attributes

Param Name

Data Type

Description

content

string

required,
max chars : 50000

Content of the comment

attachmentIds

JSONArray

optional

IDs of files to attach to the comment

POST /api/v1/communityTopics/{id}/comments

OAuth Scope

Desk.community.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Comment 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/comments/4000000019029/attachments/4000000019027/content?orgId=123456"
  } ],
  "replies" : [ ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "id" : "4000000019029",
  "content" : "Comment 1",
  "status" : "PUBLISHED"
}

Add reply

This API helps add a reply to a comment on a forum topic.

Attributes

Param Name

Data Type

Description

content

string

required,
max chars : 50000

Content of the reply

attachmentIds

JSONArray

optional

IDs of files to attach to the reply

POST /api/v1/communityTopics/{id}/comments/{id}/replies

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Reply 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/replies/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "parentCommentId" : "4000000019029",
  "id" : "4000000019031",
  "content" : "Reply 1",
  "status" : "PUBLISHED"
}

Update comment

This API helps update a published comment.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 50000

Content of the comment/reply

attachmentIds

JSONArray

optional

Ids of the attachments added for this topic

isBestComment

boolean

optional

Key that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.

PATCH /api/v1/communityTopics/{id}/comments/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Comment updated 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/comments/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "replies" : [ ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "id" : "4000000019031",
  "content" : "Comment updated 1",
  "status" : "PUBLISHED"
}

Update reply

This API helps update a published reply.

Attributes

Param Name

Data Type

Description

content

string

optional,
max chars : 50000

Content of the comment/reply

attachmentIds

JSONArray

optional

Ids of the attachments added for this topic

isBestComment

boolean

optional

Key that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.

PATCH /api/v1/communityTopics/{id}/comments/{id}/replies/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Reply updated 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    }
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/replies/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "parentCommentId" : "4000000019029",
  "id" : "4000000019031",
  "content" : "Reply updated 1",
  "status" : "PUBLISHED"
}

List topic comments

This API lists a particular number of comments on a topic, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 10,
range : 1-25

Number of comments to list

latestCommentsFirst

boolean

optional,
default : false

Key that defines the listing order of the comments. Setting TRUE lists the latest comments first (descending order) and setting FALSE lists the oldest comments first (ascending order).

GET /api/v1/communityTopics/{id}/comments

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-10-16T10:29:15.219Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ {
      "size" : "1166",
      "name" : "download (1).png",
      "id" : "4000000019033",
      "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019013/attachments/4000000019033/content?orgId=123456"
    } ],
    "replies" : [ ],
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "id" : "4000000019013",
    "content" : "<div>comment 1<br /></div>",
    "status" : "PUBLISHED"
  }, {
    "modifiedTime" : "2018-10-16T10:28:59.495Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ ],
    "replies" : [ {
      "modifiedTime" : "2018-10-16T10:22:46.893Z",
      "creator" : {
        "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
        "name" : "user 1",
        "id" : "7000000015971",
        "label" : {
          "preferences" : {
            "shape" : "RECTANGLE",
            "bgColor" : "#23F123",
            "textColor" : "#2CA123"
          },
          "name" : "Admin",
          "id" : "6000000158001",
          "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
        }
      },
      "attachments" : [ ],
      "createdTime" : "2018-10-16T10:22:46.893Z",
      "parentCommentId" : "4000000019029",
      "id" : "4000000019031",
      "content" : "test 3",
      "status" : "PUBLISHED"
    } ],
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "id" : "4000000019029",
    "content" : "<div>comment 3</div>",
    "status" : "PUBLISHED"
  } ]
}

Get topic comment

This API fetches a comment received on a topic.

GET /api/v1/communityTopics/{id}/comments/([0-9]+)

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-10-16T10:29:15.219Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    }
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download (1).png",
    "id" : "4000000019033",
    "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019013/attachments/4000000019033/content?orgId=123456"
  } ],
  "replies" : [ {
    "modifiedTime" : "2018-10-16T10:34:34.114Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ {
      "size" : "1166",
      "name" : "download (1).png",
      "id" : "4000000019037",
      "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019035/attachments/4000000019037/content?orgId=123456"
    } ],
    "createdTime" : "2018-10-16T10:34:20.858Z",
    "parentCommentId" : "4000000019013",
    "id" : "4000000019035",
    "content" : "<div>test 3<br /></div>",
    "status" : "PUBLISHED"
  } ],
  "createdTime" : "2018-10-16T09:41:40.077Z",
  "id" : "4000000019013",
  "content" : "<div>comment 1<br /></div>",
  "status" : "PUBLISHED"
}

Trash comment

This API deletes a comment from a topic.

POST /api/v1/communityTopics/{id}/comments/{id}/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/moveToTrash?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Trash reply

This API deletes a reply to a topic comment.

POST /api/v1/communityTopics/{id}/comments/{id}/replies/{id}/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies/{id}/moveToTrash?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Add attachment

This API uploads files to the storage space allocated for the community module.

File Params

file

Content-Type:multipart/form-data

File to upload

POST /api/v1/communityAttachments

OAuth Scope

Desk.community.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityAttachments?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "size" : "1024",
  "name" : "attachment.jpeg",
  "id" : "1004"
}

Get topic attachment

This API fetches a file attachment from a topic.

GET /api/v1/communityTopics/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/attachments/{id}/content?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get comment attachment

This API fetches a file attachment from a topic comment.

GET /api/v1/communityTopics/{id}/comments/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/attachments/{id}/content?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get reply attachment

This API fetches a file attachment from a reply to a topic comment.

GET /api/v1/communityTopics/{id}/replies/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/replies/{id}/attachments/{id}/content?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Report topic as spam

This API marks a forum topic as spam.

Attributes

Param Name

Data Type

Description

reason

String

required

Reason for marking the topic as spam

POST /api/v1/communityTopics/{id}/markSpam

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/markSpam?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reason" : "Reason for marking a topic as spam"
}'

Response Example

Report multiple topics as spam

This API marks multiple forum topics as spam.

Attributes

Param Name

Data Type

Description

topicIds

JSONArray

required

IDs of the topics that must be marked as spam

reason

String

required

Reason for marking the topic as spam

POST /api/v1/community/markAllTopicsAsSpam

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/community/markAllTopicsAsSpam?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reason" : "Reason for marking a topic as spam",
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "UNAUTHORIZED",
      "httpCode" : "401"
    }
  } ]
}

Report topic comment as spam

This API marks a comment on a forum topic as spam.

Attributes

Param Name

Data Type

Description

reason

String

required

Reason for marking the topic as spam

POST /api/v1/communityTopics/{id}/comments/{id}/markSpam

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/markSpam?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reason" : "Reason for marking a topic as spam"
}'

Response Example

Report multiple comments as spam

This API marks multiple comments on a forum topic as spam.

Attributes

Param Name

Data Type

Description

commentIds

JSONArray

required

IDs of the comments that must be marked as spam

reason

String

required

Reason for marking the comment as spam

POST /api/v1/community/markAllCommentsAsSpam

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/community/markAllCommentsAsSpam?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "reason" : "Reason for marking a topic's comment as spam",
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "UNAUTHORIZED",
      "httpCode" : "401"
    }
  } ]
}

Lock category or forum

This API locks a community category or forum and restricts posting access to users.

POST /api/v1/communityCategory/([0-9]+)/lock

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/lock?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Enable category or forum

This API enables a community category or forum and provides posting access to users.

POST /api/v1/communityCategory/([0-9]+)/enable

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/enable?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Disable category or forum

This API disables a community category or forum and restricts posting access to users.

POST /api/v1/communityCategory/([0-9]+)/disable

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/disable?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Follow a category or forum

This API helps users to follow a community category or forum.

POST /api/v1/communityCategory/([0-9]+)/follow

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/follow?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Unfollow a category or forum

This API helps end-users unfollow a community category or forum.

POST /api/v1/communityCategory/([0-9]+)/unfollow

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/unfollow?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Delete forum

This API deletes a forum from a community category. Keep in mind that only empty forums can be deleted.

DELETE /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.community.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Sort categories

This API sorts community categories in a particular order.

Attributes

Param Name

Data Type

Description

categoryIds

JSONArray

required

IDs of the community categories that must be sorted

POST /api/v1/communityCategory/sort

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/sort?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "categoryIds" : [ "20628000000020011", "20628000000020012", "20628000000020013", "20628000000020014", "20628000000020015" ]
}'

Response Example

Sort forums

This API sorts forums in a particular order.

Attributes

Param Name

Data Type

Description

categoryIds

JSONArray

required

IDs of the forums that must be sorted

POST /api/v1/communityCategory/([0-9]+)/sort

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/sort?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "categoryIds" : [ "20628000000020011", "20628000000020012", "20628000000020013", "20628000000020014", "20628000000020015" ]
}'

Response Example

Get category or forum

This API fetches the details of a community category or forum.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the category or forum. Values allowed are: postCount, followersCount, and commentCount.

GET /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isFollowing" : "true",
  "visibility" : "ALL_USERS",
  "departmentId" : "20628000000020011",
  "description" : "description",
  "groups" : [ ],
  "canAutoConvertTicket" : true,
  "childs" : [ {
    "isFollowing" : false,
    "visibility" : "ALL_USERS",
    "departmentId" : null,
    "description" : "forum 1",
    "groups" : [ ],
    "canAutoConvertTicket" : null,
    "commentCount" : "491",
    "photoUrl" : null,
    "moderation" : null,
    "name" : "forum",
    "postCount" : "246",
    "parentCategoryId" : "4000000003037",
    "id" : "4000000012009",
    "position" : "1",
    "followersCount" : "38",
    "permalink" : "forum-43",
    "child" : [ ],
    "moderators" : [ ],
    "status" : "ENABLED"
  } ],
  "commentCount" : "491",
  "photoUrl" : null,
  "moderation" : "NONE",
  "name" : "new dep",
  "postCount" : "246",
  "parentCategoryId" : "null",
  "id" : "20628000000020011",
  "position" : "1",
  "followersCount" : "38",
  "permalink" : "new-dep",
  "status" : "ENABLED",
  "moderators" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "type" : "AGENT"
  } ]
}

Get category or forum by permalink

This API fetches the details of a community category or forum, based on the permalink in the API request.

Query Params

Param Name

Data Type

Description

permalink

String

required

Permalink of the category or forum to fetch

include

string

optional,
max chars : 100

Additional information related to the category or forum. Values allowed are: postCount, followersCount, and commentCount.

GET /api/v1/communityCategoryByPermalink

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityCategoryByPermalink?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isFollowing" : "true",
  "visibility" : "ALL_USERS",
  "departmentId" : "20628000000020011",
  "description" : "description",
  "groups" : [ ],
  "canAutoConvertTicket" : true,
  "childs" : [ {
    "isFollowing" : false,
    "visibility" : null,
    "departmentId" : null,
    "description" : "forum 1",
    "groups" : [ ],
    "canAutoConvertTicket" : null,
    "commentCount" : "491",
    "photoUrl" : null,
    "moderation" : null,
    "name" : "forum",
    "postCount" : "246",
    "parentCategoryId" : "4000000003037",
    "id" : "4000000012009",
    "position" : "1",
    "followersCount" : "38",
    "permalink" : "forum-43",
    "child" : [ ],
    "moderators" : [ ],
    "status" : "ENABLED"
  } ],
  "commentCount" : "491",
  "photoUrl" : null,
  "moderation" : "NONE",
  "name" : "new dep",
  "postCount" : "246",
  "parentCategoryId" : "null",
  "id" : "20628000000020011",
  "position" : "1",
  "followersCount" : "38",
  "permalink" : "new-dep",
  "status" : "ENABLED",
  "moderators" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "type" : "AGENT"
  } ]
}

Add forum

This API adds a forum in a community category.

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the forum

parentCategoryId

long

required

ID of the community category under which the forum must be added

POST /api/v1/communityCategory

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "name" : "new forum",
  "parentCategoryId" : "20628000000020010"
}'

Response Example

{
  "isFollowing" : false,
  "visibility" : "ALL_USERS",
  "departmentId" : null,
  "groups" : [ ],
  "description" : "forum 1",
  "canAutoConvertTicket" : null,
  "photoUrl" : null,
  "moderation" : null,
  "name" : "forum",
  "parentCategoryId" : "4000000003037",
  "id" : "4000000012009",
  "position" : "1",
  "permalink" : "forum-43",
  "child" : [ ],
  "moderators" : [ ],
  "status" : "ENABLED"
}

List categories

This API lists a particular number of community categories.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the categories. Values allowed are: postCount, followersCount, and commentCount.

GET /api/v1/communityCategory

OAuth Scope

Desk.community.READ

Request Example

Response Example

{
  "categories" : [ {
    "isFollowing" : true,
    "visibility" : "LOGGED_IN_USERS",
    "departmentId" : "2000000012968",
    "description" : "category",
    "canAutoConvertTicket" : false,
    "photoUrl" : null,
    "moderation" : "NONE",
    "name" : "category",
    "parentCategoryId" : null,
    "id" : "4000000000017",
    "position" : "1",
    "permalink" : "category",
    "child" : [ {
      "isFollowing" : false,
      "visibility" : null,
      "departmentId" : null,
      "description" : "Forum 1",
      "canAutoConvertTicket" : null,
      "photoUrl" : null,
      "moderation" : null,
      "name" : "forum 1",
      "parentCategoryId" : "4000000000017",
      "id" : "4000000000033",
      "position" : "1",
      "permalink" : "forum-1",
      "child" : [ ],
      "moderators" : [ ],
      "status" : "ENABLED"
    } ],
    "moderators" : [ {
      "photoUrl" : null,
      "name" : "User 1",
      "id" : "2000000016079",
      "type" : "AGENT"
    } ],
    "status" : "ENABLED"
  }, {
    "isFollowing" : false,
    "visibility" : "LOGGED_IN_USERS",
    "departmentId" : null,
    "description" : "",
    "canAutoConvertTicket" : true,
    "photoUrl" : null,
    "moderation" : "FIRST_POST",
    "name" : "Dep 2",
    "parentCategoryId" : null,
    "id" : "4000000002005",
    "position" : "2",
    "permalink" : "dep-2",
    "child" : [ ],
    "moderators" : [ ],
    "status" : "ENABLED"
  } ]
}

Update category or forum

This API updates the details of a category or forum.

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the community category or forum

description

String

optional

A brief description of the community category or forum

visibility

String

optional

Visibility setting of the community category or forum. Values allowed are: ALL, LOGGED_IN_USERS, GROUPS and MODERATORS.

post

String

optional

Post permission setting of the community category or forum. Values allowed are: ALL, LOGGED_IN_USERS, GROUPS, MODERATORS and AGENTS.

respond

String

optional

Respond permission setting of the community category or forum. Values allowed are: ALL, LOGGED_IN_USERS, GROUPS, MODERATORS and AGENTS.

moderators

JSONArray

optional

Agents who moderate the community category or forum

groupIds

JSONArray

optional

Group Ids to associate

moderation

String

optional

Moderation setting for the community category or forum. Values allowed are: NONE (no moderation), ALL_POSTS (all posts of category will be moderated) and FIRST_POST (only the first forum post of users will be moderated).

canAutoConvertTicket

boolean

optional

Key that defines whether topics posted in the forum must be automatically converted into tickets or not

PATCH /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "visibility" : "GROUPS",
  "moderation" : "FIRST_POST",
  "groupIds" : [ "700000001671" ],
  "name" : "new dep updated",
  "description" : "description",
  "canAutoConvertTicket" : "true",
  "moderators" : [ "7000000015971" ]
}'

Response Example

{
  "isFollowing" : "false",
  "visibility" : "GROUP",
  "departmentId" : "20628000000020011",
  "description" : "description",
  "groups" : [ {
    "name" : "group - 1",
    "id" : "700000001671"
  } ],
  "canAutoConvertTicket" : true,
  "childs" : [ ],
  "photoUrl" : null,
  "moderation" : "FIRST_POST",
  "name" : "new dep updated",
  "parentCategoryId" : "null",
  "id" : "20628000000020011",
  "position" : "1",
  "permalink" : "new-dep-updated-permalink",
  "status" : "ENABLED",
  "moderators" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "type" : "AGENT"
  } ]
}

List followers of category or forum

This API lists a particular number of users who follow a community category or forum, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/communityCategory/([0-9]+)/followers

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/followers?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

Get category logo

This API fetches the logo of a community category.

GET /api/v1/communityCategory/([0-9]+)/logo/([0-9]+)

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/logo/([0-9]+)?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get topic types

This API fetches the topic types defined in the user community of your help desk portal.

GET /api/v1/communityTopicTypes

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopicTypes?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "defaultTopicType" : "QUESTION",
  "enabledTopicTypes" : [ "DISCUSSION", "ANNOUNCEMENT", "QUESTION" ],
  "disabledTopicTypes" : [ "IDEA", "PROBLEM" ]
}

Update topic type preferences

This API helps set the default topic type and enable/disable other topic types in the user community.

Attributes

Param Name

Data Type

Description

defaultTopicType

String

optional

Topic type to set as the default option in the user community. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

enabledTopicTypes

JSONArray

optional

Topic types to enable in the user community. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

PATCH /api/v1/communityTopicTypes

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopicTypes?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "defaultTopicType" : "QUESTION",
  "enabledTopicTypes" : [ "DISCUSSION", "ANNOUNCEMENT", "QUESTION" ]
}'

Response Example

Disable topic type

This API helps to disable topic types in the user community.

Attributes

Param Name

Data Type

Description

changeExisitingTopicToType

String

required

Topic type that should be applied to existing topics mapped to the disabled type. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

type

String

required

Topic type that must be disabled. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

POST /api/v1/communityTopicTypes/disable

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopicTypes/disable?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "changeExisitingTopicToType" : "PROBLEM",
  "type" : "QUESTION"
}'

Response Example

Get community preferences

This API fetches the settings defined for the user community in your help desk portal.

GET /api/v1/communityPreferences

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityPreferences?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "landingPage" : "ALL_CATEGORY"
}

Set community preferences

This API helps define the settings for the user community in your help desk portal.

Attributes

Param Name

Data Type

Description

landingPage

String

required

Key that determines the content to display on the home page of the user community. Values allowed are: ALLCATEGORIES (all community categories are displayed), and RECENTPOSTS (only the latest topics in the community are displayed).

POST /api/v1/communityPreferences

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityPreferences?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "landingPage" : "ALL_CATEGORY"
}'

Response Example

Update user status in community

This API updates the moderation status of end-users in the user community.

Attributes

Param Name

Data Type

Description

isModerated

boolean

optional

Key that defines whether the user is moderated or not

PATCH /api/v1/communityUsers/([0-9]+)

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityUsers/7000000015971?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isModerated" : "true"
}'

Response Example

Follow user

This API helps to follow users.

POST /api/v1/communityUsers/([0-9]+)/follow

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/7000000015971/follow?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Unfollow user

This API helps to unfollow users.

POST /api/v1/communityUsers/([0-9]+)/unfollow

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/7000000015971/unfollow?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Approve topics

This API helps to approve topics and publish them on the forum.

Attributes

Param Name

Data Type

Description

topicIds

JSONArray

required

IDs of the topics that must be approved

POST /api/v1/communityTopics/approve

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/approve?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Restore trashed topics

This API restores topics from trash.

Attributes

Param Name

Data Type

Description

topicIds

JSONArray

required

IDs of the topics that must be approved

POST /api/v1/communityTopics/restore

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/restore?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : "null"
  } ]
}

Trash unmoderated topics

This API trashes forum topics that are yet to be moderated for publishing.

Attributes

Param Name

Data Type

Description

topicIds

JSONArray

required

IDs of the topics that must be approved

POST /api/v1/communityTopics/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/moveToTrash?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Permanently delete topics

This API permanently deletes forum topics from the trash.

Attributes

Param Name

Data Type

Description

topicIds

JSONArray

required

IDs of the topics that must be approved

DELETE /api/v1/communityTopics

OAuth Scope

Desk.community.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/communityTopics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : "null"
  } ]
}

Approve comments

This API approves comments that are pending moderation.

Attributes

Param Name

Data Type

Description

commentIds

JSONArray

required

Array of comment ids

POST /api/v1/communityComments/approve

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/approve?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Restore trashed comments

This API restores comments that were trashed from forum topics.

Attributes

Param Name

Data Type

Description

commentIds

JSONArray

required

Array of comment ids

POST /api/v1/communityComments/restore

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/restore?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Trash unmoderated comments

This API trashes comments that are yet to be approved for publishing on a forum topic.

Attributes

Param Name

Data Type

Description

commentIds

JSONArray

required

Array of comment ids

POST /api/v1/communityComments/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/moveToTrash?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Permanently delete comments

This API permanently deletes comments from the trash of your help desk portal.

Attributes

Param Name

Data Type

Description

commentIds

JSONArray

required

Array of comment ids

DELETE /api/v1/communityComments

OAuth Scope

Desk.community.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/communityComments?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

List moderated users

This API lists a particular number of moderated end-users, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 25,
range : 1-25

Number of users to list

GET /api/v1/communityModeratedUsers

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityModeratedUsers?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "id" : "7000000015971",
    "type" : "AGENT",
    "status" : "ACTIVE"
  }, {
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015974/photo?orgId=123456",
      "name" : "user 4",
      "id" : "7000000015974",
      "type" : "AGENT"
    },
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "id" : "7000000015972",
    "type" : "AGENT"
  } ]
}

Unmoderate users

This API disables moderation for end-users in the user community.

Attributes

Param Name

Data Type

Description

userIds

JSONArray

required

IDs of the users for whom moderation must be disabled

POST /api/v1/communityUsers/unmoderate

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/unmoderate?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

List followers of user

This API lists followers of a user, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

int

required,
default : 1,
range : >=1

Index number, starting from which the followers must be listed

limit

int

required,
default : 10,
range : 1-25

Number of followers to list

GET /api/v1/communityUsers/{id}/followers

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015971/followers?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT",
    "status" : "ACTIVE"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT",
    "status" : "DISABLED"
  } ]
}

Get user details

This API fetches the details of an user from the community.

Query Params

Param Name

Data Type

Description

include

string

optional,
max chars : 100

Additional information related to the user. Value allowed is stats.

GET /api/v1/communityUsers/{id}

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015971?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
  "stats" : {
    "postCount" : "35",
    "topicTypeWiseCount" : {
      "ANNOUNCEMENT" : "3",
      "IDEA" : "10",
      "DISCUSSION" : "0",
      "PROBLEM" : "2",
      "QUESTION" : "20"
    },
    "followersCount" : "1",
    "commentCount" : "24"
  },
  "name" : "user 1",
  "isModerated" : true,
  "id" : "7000000015971",
  "type" : "AGENT",
  "status" : "ACTIVE"
}

List topics by user

This API lists a particular number of topics by a user, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-25

Number of topics to list

type

String

optional

Type of topics. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

startTime

date

optional

Starting time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

GET /api/v1/communityUsers/([0-9]+)/topics

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015972/topics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "latestCommentTime" : "2018-10-16T10:42:12.716Z",
    "subject" : "Topic 2",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "type" : "QUESTION",
    "latestCommenter" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015172/photo?orgId=123456",
      "name" : "user 3",
      "id" : "7000000015172",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "commentCount" : "1",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "latestCommentTime" : "2018-10-16T09:41:33.202Z",
    "subject" : "Topic 1",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "type" : "QUESTION",
    "latestCommenter" : null,
    "commentCount" : "0",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

List comments by user

This API lists a particular number of comments by a user, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the comments must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 25,
range : 1-25

Number of comments to list

startTime

date

optional

Starting time of the time range in which the comments should have been created. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range in which the comments should have been created. The value must be expressed according to the GMT time zone.

GET /api/v1/communityUsers/([0-9]+)/comments

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/7000000015971/comments?orgId=1233456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "Comment 1",
    "topicPeramlink" : "zoho-desk-api",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT"
    },
    "topicId" : "4000000019013",
    "subject" : "Zoho Desk API",
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "parentCommentId" : "4000000019012",
    "id" : "4000000019013",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED",
    "topicType" : "PROBLEM"
  }, {
    "summary" : "Comment 2",
    "topicPeramlink" : "zoho-desk-api-features",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "topicId" : "4000000019013",
    "subject" : "Zoho Desk API Features",
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "parentCommentId" : null,
    "id" : "4000000019029",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED",
    "topicType" : "PROBLEM"
  } ]
}

List topics pending moderation

This API lists a particular number of forum topics that are pending moderation, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 10,
range : 1-25

Number of topics to list

status

String

required

Moderation status of the topics. Values allowed are: AWAITINGAPPROVAL, SPAM, and TRASHED.

GET /api/v1/communityModeration/topics

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityModeration/topics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "label" : null,
      "type" : "AGENT"
    },
    "trashedBy" : null,
    "subject" : "Topic 2",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "type" : "QUESTION",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "AWAITINGAPPROVAL"
  }, {
    "summary" : "Topic 1 dscription",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "trashedBy" : null,
    "subject" : "Topic 1",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "type" : "QUESTION",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "AWAITINGAPPROVAL"
  } ]
}

List comments pending moderation

This API lists a particular number of comments that are pending moderation, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the comments must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 25,
range : 1-25

Number of comments to list

status

String

required

Moderation status of the comments. Values allowed are: AWAITINGAPPROVAL, SPAM, and TRASHED.

GET /api/v1/communityModeration/comments

OAuth Scope

Desk.community.READ

Request Example

Response Example

{
  "data" : [ {
    "summary" : "Comment 1",
    "topicPeramlink" : "zoho-desk-api",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "topicId" : "4000000019013",
    "trashedBy" : null,
    "subject" : "Zoho Desk API",
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "id" : "4000000019013",
    "categoryId" : "4000000019012",
    "status" : "AWAITINGAPPROVAL"
  }, {
    "summary" : "Comment 2",
    "topicPeramlink" : "zoho-desk-api-features",
    "modifiedTime" : "2018-10-16T10:28:59.495Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "topicId" : "4000000019013",
    "trashedBy" : null,
    "subject" : "Zoho Desk API Features",
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "id" : "4000000019029",
    "categoryId" : "4000000019012",
    "status" : "AWAITINGAPPROVAL"
  } ]
}

Draft topic

This API saves a draft of a forum topic.

Attributes

Param Name

Data Type

Description

subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

POST /api/v1/communityTopics/saveDraft

OAuth Scope

Desk.community.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/saveDraft?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "type" : "QUESTION",
  "isSticky" : false,
  "categoryId" : "4000000000017",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "notifyMe" : true
}

Update Drafted Topic

This API helps update the draft of a forum topic.

Attributes

Param Name

Data Type

Description

subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

PUT /api/v1/communityTopics/([0-9]+)/updateDraft

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/updateDraft?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "type" : "QUESTION",
  "isSticky" : false,
  "categoryId" : "4000000000017",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "notifyMe" : true
}

Publish topic draft

This API publishes the draft of a forum topic.

Attributes

Param Name

Data Type

Description

subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

mailTo

JSONArray

optional

Email IDs to which the topic must be sent after publishing

POST /api/v1/communityTopics/([0-9]+)/publishDraft

OAuth Scope

Desk.community.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/publishDraft?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "mailTo" : [ "user1@zohocorp.com" ],
  "type" : "QUESTION",
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "viewCount" : "1",
  "isTicketCreated" : false,
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "type" : "AGENT"
  },
  "isFollowing" : false,
  "label" : "NOSTATUS",
  "isVoted" : true,
  "commentCount" : "2",
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "followersCount" : "0",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "notifyMe" : false
}

Delete topic draft

This API deletes a topic draft from the user community.

DELETE /api/v1/communityTopics/([0-9]+)/deleteDraft

OAuth Scope

Desk.community.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/deleteDraft?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get moderation stats

This API fetches statistics related to topic/comment moderation in the user community.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category for which the statistics must be fetched

GET /api/v1/communityModeration/counts

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityModeration/counts?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "awaitingApproval" : {
    "comments" : "35",
    "topic" : "25"
  },
  "moderated" : {
    "topic" : "25"
  },
  "spam" : {
    "comments" : "35",
    "topic" : "25"
  },
  "trash" : {
    "comments" : "35",
    "topic" : "25"
  }
}

List moderated topics

This API lists a particular number of moderated topics, based on the limit defined.

Query Params

Param Name

Data Type

Description

categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-25

Number of topics to list

GET /api/v1/communityModeratedTopics

OAuth Scope

Desk.community.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityModeratedTopics?orgId=123456
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "subject" : "Topic 2",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "type" : "QUESTION",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 dscription",
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "type" : "END_USER"
    },
    "subject" : "Topic 1",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "type" : "QUESTION",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

Check Permalink Availability

API to check whether the given permalink is available

Query Params

Param Name

Data Type

Description

permalink

String

required

Permalink for which the availablilty need to be checked

GET /api/v1/communityTopics/permalink/availability

OAuth Scope

Desk.community.GET

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/permalink/availability?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "available" : "true"
}

Get Topic Permalinks

API to get all permalinks of a topic

GET /api/v1/communityTopics/([0-9]+)/permalinks

OAuth Scope

Desk.community.GET

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/1234567890/permalinks?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isPrimary" : "true",
    "permalink" : "community-topic-permalink-primary"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-1"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-2"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-3"
  } ]
}

Update Topic Permalinks

API to update all permalinks of a topic

Attributes

Param Name

Data Type

Description

primaryPermalink

String

optional

holds the primary permalink of a topic

secondaryPermalink

JSONArray

optional

holds the secondary permalink of a topic as array

PATCH /api/v1/communityTopics/([0-9]+)/permalinks

OAuth Scope

Desk.community.PATCH

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/1234567890/permalinks?orgId=1234567
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "primaryPermalink" : "community-topic-permalink-primary", "secondaryPermalink" : [ "community-topic-permalink-secondary-1", "community-topic-permalink-secondary-2", "community-topic-permalink-secondary-3" ] }'

Response Example

{
  "data" : [ {
    "isPrimary" : "true",
    "permalink" : "community-topic-permalink-primary"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-1"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-2"
  }, {
    "isPrimary" : "false",
    "permalink" : "community-topic-permalink-secondary-3"
  } ]
}

BugTracker

Bug tracker related REST API's

ATTRIBUTES

Attribute Name

Data Type

Description

description

string

description of bug

title

string

Tiltel of Bug

projectId

long

project Id of bug to file

threadId

long

threadId

Get Linked Tickets by Bug Id

This API fetches support tickets associated with the Bug Id specified in the API request.

GET /api/v1/bug/{bugId}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/bug/4000000003023/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

Ticket Count

Ticket count refers to the number of tickets raised across all the departments in your help desk.

Note:
1. Query parameters, especially those of string type, pertaining to count APIs must be URL-encoded.
2. New resources added to your help desk might take some time to be indexed for search. Therefore, if API responses do not reflect the updated ticket count, wait for a few minutes and try again.

Example of CustomField Data Without URL Encoding:
customField1=cf_ModelName:F3z3
customField2=cf_phone:9022334455
customField3=cf_permanentAddress: Wall Street

Example of CustomField Data with URL Encoding:
customField1=cf_ModelName%3AF3z3
customField2=cf_phone%3A9022334455
customField3=cf_permanentAddress%3AWall%20Street

Get ticket count

This API returns the ticket count of your help desk.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which ticket count must be fetched. If you do not pass this parameter in the API request, ticket count across all departments will be returned.

assigneeId

long

optional

ID of the agent assigned to resolve the ticket

contactId

long

optional

ID of the contact who raised the ticket

category

String

optional

Category of the ticket

customField1

String

optional

User-defined field in the ticket

customField2

String

optional

User-defined field in the ticket

customField3

String

optional

User-defined field in the ticket

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

GET /api/v1/ticketsCount

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketsCount
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketCountAPI ticketCount = ZDesk.getTicketCountAPIInstance(mailId);
Map<String, Object> response = ticketCount.getTicketsCount(customField1, contactId, customField2, customField3, departmentId, createdTimeRange, modifiedTimeRange, category, assigneeId );

Response Example

{
  "count" : 200
}

Get ticket count by field

This API returns the ticket count of your help desk, filtered by a specific field.

Query Params

Param Name

Data Type

Description

departmentId

long

optional

ID of the department from which ticket count must be fetched. If you do not pass this parameter in the API request, ticket count across all departments will be returned.

assigneeId

long

optional

ID of the agent assigned to resolve the ticket

contactId

long

optional

ID of the contact who raised the ticket

category

String

optional

Category of the ticket

customField1

String

optional

User-defined field in the ticket

customField2

String

optional

User-defined field in the ticket

customField3

String

optional

User-defined field in the ticket

createdTimeRange

timestamp

optional

modifiedTimeRange

timestamp

optional

field

String

required

Field by which the ticket count must be filtered. Values allowed are.
status,

priority,

channel,

statusType

GET /api/v1/ticketsCountByFieldValues

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/ticketsCountByFieldValues?field=status,priority
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

TicketCountAPI ticketCount = ZDesk.getTicketCountAPIInstance(mailId);
Map<String, Object> response = ticketCount.getTicketsCountByField(field, customField1, contactId, customField2, customField3, departmentId, createdTimeRange, modifiedTimeRange, category, assigneeId );

Response Example

{
  "priority" : [ {
    "count" : "123",
    "value" : "high"
  } ],
  "status" : [ {
    "count" : "123",
    "value" : "open"
  } ]
}

Jira

Jira, developed by Atlassian, is one of the leading bug-tracking tools in the industry. Jira’s integration with Zoho Desk helps in instantly filing issues in Jira right from a customer support ticket in Desk. These APIs pertain to the integration between these tools.

Example

{ "issueId" : "10010", "issueKey" : "SD-5", "componentId" : "[]", "reporter" : { "name" : "Albertjoseph", "key" : "admin" }, "priority" : { "name" : "high", "id" : "3" }, "transitionInfo" : [ { "issueStatusCategory" : "new", "issueStatus" : "Backlog", "transitionId" : "11" }, { "issueStatusCategory" : "done", "issueStatus" : "Done", "transitionId" : "13" } ], "issueType" : "Task", "deskCustomFieldId" : "customField_10366", "projectKey" : "SD", "mandatoryFields" : [ { "type" : "string", "value" : "sample", "key" : "labels" } ], "assignee" : { "name" : "Albertjoseph", "key" : "admin" }, "ticketId" : "15433022532322", "issueDescription" : "TEST", "issueSummary" : "Boston testing" }

Get Linked Tickets by Jira Issue Id

This API fetches support tickets associated with the Jira issue specified in the API request.

GET /api/v1/jiraIssue/{issueId}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/jiraIssue/190176/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "assignee" : {
      "firstName" : "Robert",
      "lastName" : "John"
    },
    "priority" : "High",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "Smith"
    },
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

Badgification

Gamification refers to the concept of applying game-based practices, principles, and incentives for non-game activities in any environment. This is generally done in the form of providing points, virtual badges and trophies, and so on to individuals who show deep involvement in the activity. In Zoho Desk, gamification is currently available in the user community. End-customers who actively participate in community forum discussions receive badges and credits and move up from one level to the next when they fulfill certain conditions. The expected outcome of gamification in this context is more solutions from customers and lesser burden on support agents.

List badges

This API lists a particular number of default and custom badges, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

Index number starting from which the badges must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of badges to list

type

string

optional,
max chars : 100

Type of badge: default or custom

GET /api/v1/badges

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/badges
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "name" : "Badge 1",
  "isCustom" : "false",
  "description" : "Best Contributor",
  "levelName" : null,
  "id" : "1",
  "iconUrl" : "https://www.zylker.com/badge1.jpg"
} ]

Add badge

This API adds a badge to your user community.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the badge

description

string

optional,
max chars : 200

Description of the badge

isCustom

boolean

required

Key that specifies if the badge is user-defined or not

customIconId

int

optional

ID of the file attachment that contains the badge icon

defaultIconId

int

optional

ID of the default icon

POST /api/v1/badges

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/badges
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Badge 1", "isCustom" : "true", "description" : "Best Contributor", "defaultIconId" : "1" }'

Response Example

{
  "name" : "Badge 1",
  "isCustom" : "true",
  "description" : "Best Contributor",
  "levelName" : null,
  "id" : "1",
  "iconUrl" : "https://www.zylker.com/badge1.jpg"
}

Update badge

This API updates the details of a badge.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the badge

description

string

optional,
max chars : 200

Description of the badge

customIconId

int

optional

ID of the file attachment that contains the badge icon

defaultIconId

int

optional

ID of the default icon

PUT /api/v1/badges/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/badges/3000000000010
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Badge 2", "description" : "Top Contributor", "customIconId" : "3000000000017" }'

Response Example

{
  "name" : "Badge 2",
  "isCustom" : "true",
  "description" : "Top Contributor",
  "levelName" : null,
  "id" : "3000000000010",
  "iconUrl" : "https://www.zylker.com/badge2.jpg"
}

Delete badge

This API deletes a badge from the user community.

DELETE /api/v1/badges/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/badges/3000000000010
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List levels

This API lists a particular number of levels, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

Index number, starting from which the levels must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of limits to list

GET /api/v1/levels

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/levels
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000345",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "200",
  "name" : "Level 1",
  "description" : "Beginner",
  "id" : "3000000000335"
} ]

Add level

This API adds a level to the user community.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the level

description

string

optional,
max chars : 200

Description of the level

badgeId

long

optional

ID of the badge to associate with the level

pointsToReach

double

required

Minimum number of credits a user needs to reach the level

POST /api/v1/levels

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/levels
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "pointsToReach" : "200", "badgeId" : "3000000000345", "name" : "Level 1", "description" : "Beginner" }'

Response Example

{
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000395",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "200",
  "name" : "Level 1",
  "description" : "Beginner",
  "id" : "1"
}

Update level

This API updates the details of a level.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the level

description

string

optional,
max chars : 200

Description of the level

badgeId

long

optional

ID of the badge to associate with the level

pointsToReach

double

required

Minimum number of credits a user needs to reach the level

PUT /api/v1/levels/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/levels/3000000000345
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "pointsToReach" : "300", "name" : "Level 2", "description" : "Beginner" }'

Response Example

{
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000356",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "300",
  "name" : "Level2",
  "description" : "Beginner",
  "id" : "3000000000345"
}

Delete level

This API deletes a level from the user community.

DELETE /api/v1/levels/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/levels/3000000000345
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List creditworthy activities

This API lists a particular number of creditworthy activities, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

Index number, starting from which the activities must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of activities to list

type

string

optional,
max chars : 100

Type of creditworthy activity: default of custom

GET /api/v1/credits

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/credits
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "isEnabled" : "true",
  "name" : "Post Idea",
  "isCustom" : "false",
  "description" : "Post an Idea to get 100 points",
  "id" : "3000000000315",
  "points" : "100"
}, {
  "isEnabled" : "true",
  "name" : "Post Question",
  "isCustom" : "false",
  "description" : "Post a Question to get 50 points",
  "id" : "3000000000320",
  "points" : "50"
} ]

Add creditworthy activity

This API adds a creditworthy activity to the user community.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the creditworthy activity

description

string

optional,
max chars : 200

Description of the creditworthy activity

points

double

required

Number of credits associated with the activity

POST /api/v1/credits

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/credits
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Custom Credit", "description" : "This is given to the people who have attended Webinar", "points" : "100" }'

Response Example

{
  "isEnabled" : "true",
  "name" : "Custom Credit",
  "isCustom" : "true",
  "description" : "This is given to the people who have attended Webinar",
  "id" : "3000000000343",
  "points" : "100"
}

Update creditworthy activity

This API updates a creditworthy activity.

Attributes

Param Name

Data Type

Description

name

string

required,
max chars : 200

Name of the creditworthy activity

description

string

optional,
max chars : 200

Description of the creditworthy activity

isEnabled

boolean

optional

Key that specifies if the activity is enabled or not

points

double

required

Number of credits associated with the activity

PUT /api/v1/credits/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/credits/3000000000335
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "name" : "Active User", "description" : "This is given to the people who are active", "points" : "200" }'

Response Example

{
  "isEnabled" : "true",
  "name" : "Active User",
  "isCustom" : "true",
  "description" : "This is given to the people who are highly active",
  "id" : "3000000000335",
  "points" : "200"
}

Delete creditworthy activity

This API deletes a creditworthy activity from the user community.

DELETE /api/v1/credits/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/credits/3000000000375
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List credit holders

This API lists a particular number of users with credits, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

Index number, starting from which the users must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/credits/([0-9]+)/users

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/credits/3000000000435/users
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "users" : [ {
    "name" : "Jade Tywin",
    "id" : "3000000000485"
  }, {
    "name" : "Steve",
    "id" : "3000000000487"
  } ]
}

Add credit holders

This API adds the users specified in the request to the credit holders list.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users who must be added as credit holders

POST /api/v1/credits/([0-9]+)/associateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/credits/3000000000300/associateUsers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3000000000985", "3000000000485" ]
}'

Response Example

Remove credit holders

This API removes users from the custom holders list.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users who must be added as credit holders

POST /api/v1/credits/([0-9]+)/dissociateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/credits/3000000000300/dissociateUsers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3000000000885", "3000000000495", "3000000000285" ]
}'

Response Example

List badge holders

This API lists a particular number of users with badges, based on the limit defined.

Query Params

Param Name

Data Type

Description

from

Integer

required,
default : 1,
range : >0

Index number, starting from which the users must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/badges/([0-9]+)/users

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/badges/3000000000185/users
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "users" : [ {
    "name" : "Jade Tywin",
    "id" : "3000000000455"
  }, {
    "name" : "Steve",
    "id" : "3000000000385"
  } ]
}

Add badge holders

This API adds the users specified in the request to the badge holders list.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users who must be added as badge holders

POST /api/v1/badges/([0-9]+)/associateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/badges/3000000000375/associateUsers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3000000000378", "3000000000395" ]
}'

Response Example

Remove badge holders

This API removes users from the badge holders list.

Attributes

Param Name

Data Type

Description

userIds

list

required

IDs of the users who must be added as badge holders

POST /api/v1/badges/([0-9]+)/dissociateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/badges/3000000000893/dissociateUsers
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "userIds" : [ "3000000000813", "3000000000193", "3000000000903" ]
}'

Response Example

List available icons

This API lists all icons that are not assigned to any badges in the user community.

GET /api/v1/availableBadgeIcons

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/availableBadgeIcons
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "id" : "3000000000234",
  "iconUrl" : "https://www.zylker.com/pic1.jpg"
}, {
  "id" : "3000000000722",
  "iconUrl" : "https://www.zylker.com/pic2.jpg"
} ]

HolidayList

Holiday list refers to the list of public holidays applicable to your help desk. In Zoho Desk, you can configure multiple holiday lists, based on the regions you cater to. Holiday lists are factored in calculating the due time for responding to and resolving tickets. They play a critical role in time tracking and SLAs. You can associate a holiday list with multiple business hour sets, but each business hour set can include only one holiday list.

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the holiday list

holidays

show Attributes

list

Holidays to define in the list

status

String

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds

list

IDs of the business hour sets associated with the holiday list

Example

{ "modifiedTime" : "2018-12-03T07:16:54.223Z", "associatedBusinessHours" : [ { "businessHourStatus" : "ACTIVE", "businessHourId" : "4000000101005", "businessHourName" : "Dual Write OFF 2" }, { "businessHourStatus" : "INACTIVE", "businessHourId" : "4000000101009", "businessHourName" : "Dual Write OFF 3 to ON via Update" } ], "holidays" : [ { "from" : "03-26", "to" : "03-26", "holidayName" : "Regional Holidays" }, { "from" : "12-05", "to" : "12-05", "holidayName" : "November Holidays" } ], "createdBy" : "4000000016079", "name" : "General HolidayList", "createdTime" : "2018-11-28T13:04:53.327Z", "modifiedBy" : "4000000016079", "id" : "4000000105030", "status" : "ACTIVE" }

Create holiday list

This API creates a holiday list in your help desk portal

Attributes

Param Name

Data Type

Description

name

String

required

Name of the holiday list

holidays

list

required

Holidays to define in the list

status

String

required

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds

list

optional

IDs of the business hour sets associated with the holiday list

POST /api/v1/holidayList

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/holidayList
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "associatedBusinessHourIds" : [ "4000000101003", "4000000101005", "4000000103001" ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "name" : "My Company Holidays",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T10:36:53.136Z",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101005",
    "businessHourName" : "Indian Night Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "name" : "My Company Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Get holiday list

This API fetches the details of a holiday list configured in your help desk portal

GET /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/holidayList/4000000191371
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-12-10T10:36:53.136Z",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101005",
    "businessHourName" : "Indian Night Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "name" : "My Company Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Update holiday list

This API updates the details of a holiday list configured in your help desk portal

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the holiday list

holidays

list

optional

Holidays to define in the list

status

String

optional

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds

list

optional

IDs of the business hour sets associated with the holiday list

PATCH /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/holidayList/6000000045009
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "associatedBusinessHourIds" : [ "4000000101003", "4000000103001" ],
  "name" : "My Holidays"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T10:44:46.247Z",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "name" : "My Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Delete holiday list

This API deletes a holiday list from your help desk portal

DELETE /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/holidayList/4000000191371
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List holiday lists

This API lists a particular number of holiday lists, based on the limit specified

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the holiday lists must be listed

limit

integer

optional,
range : 1-50

Number of holiday lists to list

status

String

optional

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

GET /api/v1/holidayList

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/holidayList
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-12-10T10:48:48.772Z",
    "associatedBusinessHours" : [ {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000101003",
      "businessHourName" : "UK Day Shift"
    }, {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000103001",
      "businessHourName" : "UK Night Shift"
    }, {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000101005",
      "businessHourName" : "Indian Night Shift"
    } ],
    "createdBy" : "4000000016079",
    "name" : "My Company Holidays",
    "createdTime" : "2018-12-10T10:48:48.772Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000191456",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-10T10:35:36.071Z",
    "associatedBusinessHours" : [ ],
    "createdBy" : "4000000016079",
    "name" : "My Holidays",
    "createdTime" : "2018-12-10T10:35:36.071Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000191337",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T14:56:17.481Z",
    "associatedBusinessHours" : [ ],
    "createdBy" : "4000000016079",
    "name" : "Overlapping Holidays",
    "createdTime" : "2018-12-03T13:27:30.454Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000117001",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:54.223Z",
    "associatedBusinessHours" : [ {
      "businessHourStatus" : "INACTIVE",
      "businessHourId" : "4000000101009",
      "businessHourName" : "Indian Shift"
    } ],
    "createdBy" : "4000000016079",
    "name" : "General HolidayList",
    "createdTime" : "2018-11-28T13:04:53.327Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000105030",
    "status" : "ACTIVE"
  } ]
}

Notification

Notifications are automated messages that alert end-users, including contacts and agents, of any support-related activities or updates

ATTRIBUTES

Attribute Name

Data Type

Description

departmentId
see documentation

Long

ID of the department in which the notification is configured

departmentName

String

Name of the department in which the notification is configured

channel

String

Channel through which the ticket was received

ticketNumber

Long

Serial number of the ticket in the help desk portal

ticketId

Long

ID of the ticket

subject

String

Subject of the ticket

threadId

Long

ID of the thread

errorMessage

String

Error message in the email delivery failure thread

reason

String

Reason for email delivery failure

assignee

show Attributes

object

Agent assigned to resolve the ticket

requester

show Attributes

object

Details of user who requested for the approval

description

String

Description of the approval

Example

{ "departmentName" : "Sales", "threadId" : "4000002350527", "requester" : { "firstName" : "", "lastName" : "Smith", "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo", "id" : "5000000012902", "email" : null }, "ticketNumber" : "102", "reason" : "452 4.3.1 Temporary System Error", "subject" : "zPhone not working", "departmentId" : "4000000019077", "channel" : "EMAIL", "errorMessage" : "Error while processing the request! Unable to send message;", "assignee" : { "firstName" : "John", "lastName" : "Carol", "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo", "id" : "1892000000056007", "email" : "carol@zylker.com" }, "ticketId" : "4000000014345" }

List email delivery failure alerts

This API lists the email delivery failure alerts configured in a particular department.

Query Params

Param Name

Data Type

Description

department

String

required

ID of the department from which the email delivery failure alerts must be fetched. You can pass a specific department ID or allDepartment in the API request.

from

Integer

optional

Index number, starting from which the alerts must be listed

limit

Integer

optional,
range : 1-50

Number of alerts to list

GET /api/v1/emailFailureAlerts

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/emailFailureAlerts?department=1892000000056007&from=1&limit=20
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "departmentName" : "Sales",
    "threadId" : "4000002350527",
    "ticketNumber" : "102",
    "reason" : "452 4.3.1 Temporary System Error",
    "subject" : "zPhone not working",
    "departmentId" : "4000000019077",
    "channel" : "EMAIL",
    "errorMessage" : "Error while processing the request! Unable to send message;",
    "assignee" : {
      "firstName" : "John",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "ticketId" : "4000000014345"
  }, {
    "departmentName" : "Marketing",
    "threadId" : "4000002353427",
    "ticketNumber" : "102",
    "reason" : "Email reply failed from being sent! Momentary issues with the mail server, Try resending this email again.",
    "subject" : "zPhone not working",
    "departmentId" : "4000000019067",
    "channel" : "TWITTER",
    "errorMessage" : "null",
    "assignee" : {
      "firstName" : "John",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "ticketId" : "4000000014335"
  } ]
}

Clear email delivery failure alerts

This API deletes all email delivery failure alerts configured in a particular department.

Query Params

Param Name

Data Type

Description

department

String

required

ID of the department from which the email delivery failure alerts must be deleted. You can pass a specific department ID or allDepartment in the API request

PATCH /api/v1/emailFailureAlerts

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/emailFailureAlerts?department=1892000000056007
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Get my pending approvals

This API lists the pending approvals for a given user

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the pending approvals for a give user must be fetched.

department

String

required

ID of the department from which pending approvals must be fetched. You can pass a specific department ID or allDepartment in the API request.

limit

integer

required,
default : 10,
range : 1-100

Number of pending approvals to list

GET /api/v1/myPendingApprovals

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/myPendingApprovals?department=1892000000056007&from=10&limit=20
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "myPendingApprovals" : [ {
    "departmentName" : "Sales",
    "requester" : {
      "firstName" : "",
      "lastName" : "Smith",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
      "id" : "5000000012902",
      "email" : null
    },
    "ticketNumber" : "102",
    "subject" : "Sample subject",
    "departmentId" : "4000000019077",
    "createdTime" : "2019-06-21T13:16:14.000Z",
    "description" : "Sample description",
    "id" : "4000002350527",
    "ticketId" : "4000002350527"
  }, {
    "departmentName" : "Marketing",
    "requester" : {
      "firstName" : "",
      "lastName" : "John",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012932/photo",
      "id" : "5000000012932",
      "email" : null
    },
    "ticketNumber" : "102",
    "subject" : "Sample subject",
    "departmentId" : "4000000019067",
    "createdTime" : "2019-06-21T13:16:14.000Z",
    "description" : "",
    "id" : "4000002350527",
    "ticketId" : "4000000014335"
  } ],
  "assignee" : {
    "firstName" : "John",
    "lastName" : "Carol",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
    "id" : "1892000000056007",
    "email" : "carol@zylker.com"
  }
}

Data Sharing Rules

Data sharing rules refer to user permissions related to viewing and/or editing resources in the different modules in Zoho Desk.

ATTRIBUTES

Attribute Name

Data Type

Description

contracts

string

Data sharing rules related to SLA contracts

tickets

string

Data sharing rules related to tickets

contacts

string

Data sharing rules related to contacts

accounts

string

Data sharing rules related to accounts

products

string

Data sharing rules related to products

tasks

string

Data sharing rules related to tasks

calls

string

Data sharing rules related to calls

events

string

Data sharing rules related to events

Example

{ "tickets" : "public", "calls" : "public read only", "accounts" : "public read only", "contracts" : "private", "contacts" : "public", "tasks" : "private", "events" : "public", "products" : "public" }

Get data sharing rules

This API fetches the different data sharing rules configured in your help desk portal.

GET /api/v1/dataSharingRules

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/dataSharingRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "tickets" : "public",
  "calls" : "public read only",
  "accounts" : "public read only",
  "contracts" : "private",
  "contacts" : "public",
  "tasks" : "private",
  "events" : "public",
  "products" : "public"
}

Update data sharing rules

This API updates the data sharing rules configured in your help desk portal.

Attributes

Param Name

Data Type

Description

contracts

string

optional,
max chars : 100

Data sharing rules related to SLA contracts

tickets

string

optional,
max chars : 100

Data sharing rules related to tickets

contacts

string

optional,
max chars : 100

Data sharing rules related to contacts

accounts

string

optional,
max chars : 100

Data sharing rules related to accounts

products

string

optional,
max chars : 100

Data sharing rules related to products

tasks

string

optional,
max chars : 100

Data sharing rules related to tasks

calls

string

optional,
max chars : 100

Data sharing rules related to calls

events

string

optional,
max chars : 100

Data sharing rules related to events

PATCH /api/v1/dataSharingRules

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/dataSharingRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "tickets" : "public",
  "calls" : "public read only",
  "accounts" : "public read only",
  "contracts" : "private",
  "contacts" : "public",
  "tasks" : "private",
  "events" : "public",
  "products" : "public"
}'

Response Example

Finance

Finance related REST API's

List invoices

To list invoices.

Query Params

Param Name

Data Type

Description

deskEntityId

long

optional

To fetch invoice by desk contact or account or ticket id

deskModuleName

String

required

Desk Module Name: Contacts or Cases or Accounts

departmentId

long

optional

Department Id

status

string

optional,
max chars : 100

To fetch invoice by status, Available status are sent, draft, overdue, paid, void, unpaid, partially_paid and viewed

pageNumber

integer

optional

page number

GET /api/v1/zohoFinance/{financeService}/invoices

OAuth Scope

Desk.integrations.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/zohoFinance/books/invoices
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "deskEntityId" : "5000000014010",
  "data" : [ {
    "date" : "2018-09-23",
    "total" : 117,
    "isViewdByClient" : false,
    "totalFormatted" : "AED117.00",
    "invoiceNumber" : "INV-000025",
    "id" : "1332784000000108001",
    "dateFormatted" : "23 Sep 2018",
    "currencyCode" : "AED",
    "statusFormatted" : "Draft",
    "status" : "draft"
  } ],
  "deskModuleName" : "Contacts"
}

Update invoice status

This will update status of invoice.

Attributes

Param Name

Data Type

Description

status

string

optional,
max chars : 100

status to be updated

PATCH /api/v1/zohoFinance/{financeService}/invoices/{id}

OAuth Scope

Desk.integrations.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/zohoFinance/books/invoices/1332784000000108001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "status" : "draft"
}'

Response Example

MarkAllInvoicesSent

This will update status of invoice to sent.

Attributes

Param Name

Data Type

Description

ids

JSONArray

optional

id of the invoice or estimate

POST /api/v1/zohoFinance/{financeService}/invoices/markAsSent

OAuth Scope

Desk.integrations.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/zohoFinance/books/invoices/markAsSent
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "1332784000000108001", "1332784000000108004", "1332784000000108006" ]
}'

Response Example

List estimates

To list estimates.

Query Params

Param Name

Data Type

Description

deskEntityId

long

optional

To fetch estimates by desk contact or account or ticket id

deskModuleName

String

required

Desk Module Name. allowed modules are Contacts, Cases, Accounts

status

string

optional,
max chars : 100

To fetch estimates by status, Available status are draft, sent, invoiced , accepted, declined and expired

pageNumber

integer

optional

page number

GET /api/v1/zohoFinance/{financeService}/estimates

OAuth Scope

Desk.integrations.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/zohoFinance/books/estimates
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "deskEntityId" : "5000000014010",
  "data" : [ {
    "date" : "2018-09-23",
    "total" : 117,
    "isViewdByClient" : false,
    "estimateNumber" : "INV-000025",
    "totalFormatted" : "AED117.00",
    "id" : "1332784000000108001",
    "dateFormatted" : "23 Sep 2018",
    "currencyCode" : "AED",
    "statusFormatted" : "Draft",
    "status" : "draft"
  } ],
  "deskModuleName" : "Contacts"
}

Update estimate status

This will update status of estimate.

Attributes

Param Name

Data Type

Description

status

string

optional,
max chars : 100

status to be updated

PATCH /api/v1/zohoFinance/{financeService}/estimates/{id}

OAuth Scope

Desk.integrations.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/zohoFinance/books/estimates/1332784000000108001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "status" : "draft"
}'

Response Example

Get tickets for invoices

To get associated tickets for invoice id.

GET /api/v1/finance/invoices/{id}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/finance/invoices/7388387778738/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "assignee" : {
      "firstName" : "Robert",
      "lastName" : "John"
    },
    "priority" : "High",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "Smith"
    },
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

agentAvailability

Agent availability refers to your support agents' presence for responding to customers.

Update Agent Availability Configuration

This API updates the agent availability setting configured in your help desk portal.

Attributes

Param Name

Data Type

Description

treatIdleAgentsAsOffline

boolean

optional

Key that specifies if idle agents should be marked as offline after a particular duration.

agentIdleTime

int

optional,
range : 1-60

Duration after which idle agents should be marked as offline. The value can range from 1 to 60.

POST /api/v1/agentAvailabilityConfig

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agentAvailabilityConfig
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "agentIdleTime" : "30",
  "treatIdleAgentsAsOffline" : true
}'

Response Example

Get Agent Availability Configuration

This API fetches the agent availability setting configured in your help desk portal.

GET /api/v1/agentAvailabilityConfig

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agentAvailabilityConfig
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "agentIdleTime" : "30",
  "treatIdleAgentsAsOffline" : true
}

Get Current Availability

This API lists the current availability of agents in a particular department.

Query Params

Param Name

Data Type

Description

departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 20,
range : 1-20

Number of agents to list. The default and the maximum value allowed is 20.

from

integer

required,
default : 0,
range : 1-5999

Index number, starting from which the agents must be fetched. The default value is 0 and the maximum value allowed is 5999.

GET api/v1/agentAvailability

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agentAvailability?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "OFFLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "OFFLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "OFFLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

Get Online Agents

This API lists the agents who are currently online in a particular department.

Query Params

Param Name

Data Type

Description

departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 20,
range : 1-6000

Number of agents to list. The default value is 20 and the maximum value allowed is 6000.

GET api/v1/onlineAgents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/onlineAgents?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "ONLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

Get Offline Agents

This API lists the agents who are currently offline in a particular department.

Query Params

Param Name

Data Type

Description

departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 20,
range : 1-6000

Number of agents to list. The default value is 20 and the maximum value allowed is 6000.

GET api/v1/offlineAgents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/offlineAgents?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "ONLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "OFFLINE",
    "status" : "OFFLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "OFFLINE",
    "status" : "OFFLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

AutomationFeatureCount

A Common API to get various limits for Automation Features.

Example

{ "featureName" : "workflows", "maxTotalCount" : "40", "maxActiveCount" : "20", "usedCountInfo" : { "usedTotalCount" : "3", "usedActiveCount" : "2" } }

Get Automation Feature Count

This API is used to Get Automation Feature Limits, For BusinessHours and HoldiayList, There are no mandatory params, For Workflows valid and mandatory params are module and departmentId, Valid module param values for Workflows are tickets,contacts,contracts,accounts,tasks,products,timeEntry. For Skills and SkillTye departmentId is mandatory param

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Department Id

module

String

optional

Module, allowed values tickets,contacts,contracts,accounts,tasks,products,timeEntry

feature

String

required

Feature, allowed values businesshours,holidaylist,Skills,SkillType,workflows,blueprints

GET /api/v1/automationFeatureCount

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/automationFeatureCount?departmentId=1000000013248&module=tickets&feature=workflows
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "featureName" : "workflows",
  "maxTotalCount" : "40",
  "maxActiveCount" : "20",
  "usedCountInfo" : {
    "usedTotalCount" : "3",
    "usedActiveCount" : "2"
  }
}

Skills

Skills, They are area of expertises which can be mapped with Tickets and Agents

ATTRIBUTES

Attribute Name

Data Type

Description

name

String

Name of the skill

description

String

description of the skill

status

String

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

ID of the Skill Type

criteria

show Attributes

list

The criteria details for the skill

agentIds

list

IDs of the agents mapped with the skill

Example

{ "modifiedTime" : "2020-07-23T13:03:12.994Z", "agentIds" : [ "1000000000059" ], "skillType" : { "skillTypeId" : "1000000173001", "skillTypeName" : "Country" }, "orderId" : "2", "criteria" : { "fieldConditions" : [ { "displayValue" : [ "Russia" ], "condition" : "is", "fieldName" : "Subject", "fieldModule" : "tickets", "value" : [ "Russia" ] }, { "displayValue" : [ "987532114" ], "condition" : "is", "fieldName" : "Phone", "fieldModule" : "tickets", "value" : [ "987532114" ] } ], "pattern" : "(1or2)" }, "departmentId" : "1000000013248", "description" : "Country is Russia", "skillTypeId" : "1000000173001", "createdBy" : "1000000000059", "name" : "Russia", "createdTime" : "2020-07-23T13:03:12.994Z", "modifiedBy" : "1000000000059", "id" : "1000000173047", "status" : "ACTIVE" }

Create skill

This API Creates a skill

Attributes

Param Name

Data Type

Description

name

String

required

Name of the skill

description

String

optional

description of the skill

status

String

required

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

required

ID of the Skill Type

criteria

list

required

The criteria details for the skill

agentIds

list

optional

IDs of the agents mapped with the skill

POST /api/v1/skills

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/skills
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "skillTypeId" : "1000000173001",
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "India" ]
    }, {
      "condition" : "is",
      "fieldName" : "Phone",
      "fieldModule" : "tickets",
      "value" : [ "987532114" ]
    } ],
    "pattern" : "(1or2)"
  },
  "name" : "India",
  "description" : "Country is India",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:44:42.574Z",
  "agentIds" : [ ],
  "skillType" : {
    "skillTypeId" : "1000000173001",
    "skillTypeName" : "Country"
  },
  "orderId" : "1",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "India" ],
      "condition" : "is",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "India" ]
    }, {
      "displayValue" : [ "987532114" ],
      "condition" : "is",
      "fieldName" : "Phone",
      "fieldModule" : "tickets",
      "value" : [ "987532114" ]
    } ],
    "pattern" : "(1or2)"
  },
  "departmentId" : "1000000013248",
  "description" : "Country is India",
  "skillTypeId" : "1000000173001",
  "createdBy" : "1000000000059",
  "name" : "India",
  "createdTime" : "2020-07-23T12:44:42.574Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173029",
  "status" : "ACTIVE"
}

View skill

This API Gets the details of a skill

GET /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skills/1000000173145
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-23T13:08:36.093Z",
  "agentIds" : [ "1000000000059" ],
  "skillType" : {
    "skillTypeId" : "1000000173013",
    "skillTypeName" : "Language"
  },
  "orderId" : "5",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "Malayalam" ],
      "condition" : "contains",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "Malayalam" ]
    } ],
    "pattern" : "1"
  },
  "departmentId" : "1000000013248",
  "description" : "Language is Malayalam",
  "skillTypeId" : "1000000173013",
  "createdBy" : "1000000000059",
  "name" : "Malayalam",
  "createdTime" : "2020-07-23T13:08:36.093Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173145",
  "status" : "ACTIVE"
}

Update skill

This API Updates a skill

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the skill

description

String

optional

description of the skill

status

String

optional

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

optional

ID of the Skill Type

criteria

list

optional

The criteria details for the skill

agentIds

list

optional

IDs of the agents mapped with the skill

PATCH /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/skills/1000000173145
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "name" : "Malayalam",
  "description" : "Malayali"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T13:08:36.093Z",
  "agentIds" : [ "1000000000059" ],
  "skillType" : {
    "skillTypeId" : "1000000173013",
    "skillTypeName" : "Language"
  },
  "orderId" : "5",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "Malayalam" ],
      "condition" : "contains",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "Malayalam" ]
    } ],
    "pattern" : "1"
  },
  "departmentId" : "1000000013248",
  "description" : "Malayali",
  "skillTypeId" : "1000000173013",
  "createdBy" : "1000000000059",
  "name" : "Malayalam",
  "createdTime" : "2020-07-23T13:08:36.093Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173145",
  "status" : "ACTIVE"
}

Delete skill

This API deletes a skill from your help desk portal

DELETE /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/skills/6000000033001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List all skills

This API lists all skills in a department

Query Params

Param Name

Data Type

Description

departmentId

long

required

Department Id

from

integer

optional

Index number, starting from which the skills must be listed

limit

integer

optional,
range : 1-100

Number of skill to list, allowed minimum value 1, maximum value 100,default is 100

status

String

optional

Active inactive filter for Skills. Values allowed are ACTIVE and INACTIVE

searchString

String

optional

Search string, Used to filter skills by name starting with this string

skillTypeId

long

optional

Skill Type Id, to Filter Skills by SkillType

GET /api/v1/skills

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skills?departmentId=1000000013248
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-07-23T12:44:42.574Z",
    "agentIds" : [ ],
    "skillType" : {
      "skillTypeId" : "1000000173001",
      "skillTypeName" : "Country"
    },
    "orderId" : "1",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "India" ],
        "condition" : "is",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "India" ]
      }, {
        "displayValue" : [ "987532114" ],
        "condition" : "is",
        "fieldName" : "Phone",
        "fieldModule" : "tickets",
        "value" : [ "987532114" ]
      } ],
      "pattern" : "(1or2)"
    },
    "departmentId" : "1000000013248",
    "description" : "Country is India",
    "skillTypeId" : "1000000173001",
    "createdBy" : "1000000000059",
    "name" : "India",
    "createdTime" : "2020-07-23T12:44:42.574Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173029",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:03:12.994Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173001",
      "skillTypeName" : "Country"
    },
    "orderId" : "2",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Russia" ],
        "condition" : "is",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Russia" ]
      }, {
        "displayValue" : [ "987532114" ],
        "condition" : "is",
        "fieldName" : "Phone",
        "fieldModule" : "tickets",
        "value" : [ "987532114" ]
      } ],
      "pattern" : "(1or2)"
    },
    "departmentId" : "1000000013248",
    "description" : "Country is Russia",
    "skillTypeId" : "1000000173001",
    "createdBy" : "1000000000059",
    "name" : "Russia",
    "createdTime" : "2020-07-23T13:03:12.994Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173047",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:07:51.838Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "3",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "English" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "English" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Language is English",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "English",
    "createdTime" : "2020-07-23T13:07:51.838Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173097",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:08:16.891Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "4",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Tamil" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Tamil" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Language is Tamil",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "Tamil",
    "createdTime" : "2020-07-23T13:08:16.891Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173121",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:08:36.093Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "5",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Malayalam" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Malayalam" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Malayali",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "Malayalam",
    "createdTime" : "2020-07-23T13:08:36.093Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173145",
    "status" : "ACTIVE"
  } ]
}

List associated automation rules

This API lists a particular number of automation rules that include a skill,based on the limit specified

Query Params

Param Name

Data Type

Description

from

integer

optional

Index number, starting from which the related rules must be listed

limit

integer

optional,
range : 1-100

Number of rules to list, allowed minimum value 1, maximum value 100,default is 100

GET /api/v1/skills/{skillId}/relatedRules

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skills/10000000317019/relatedRules
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ruleType" : "SUPERVISE",
    "ruleName" : "TBA1",
    "ruleId" : "6000000019012"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Priority-based SLAs",
    "ruleId" : "6000000013508"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Bronze SLAs",
    "ruleId" : "6000000013514"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Default Blueprint",
    "ruleId" : "6000000016083"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "BH BP",
    "ruleId" : "6000000018143"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Third Bp",
    "ruleId" : "6000000023018"
  } ]
}

Reorder Skills in a Department

This API lists reorders Skills in a Department

Attributes

Param Name

Data Type

Description

skillIds

JSONArray

required

List of skill ids to reorder

departmentId

long

required

department of the skills to be reordered

POST /api/v1/skills/order

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/skills/order
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "skillIds" : [ "1000000173121", "1000000173029", "1000000173047", "1000000173097", "1000000173145" ],
  "departmentId" : "1000000013248"
}'

Response Example

Get Skills of an Agent

Returns skills mapped with an agent by department

Query Params

Param Name

Data Type

Description

departmentIds

long

required

list of Department Ids separated by commas,Maximum 10 department ids allowed

GET /api/v1/agents/{agentId}/skills

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/1000000003234/skills?departmentIds=10000000030987,10000000038722,10000000030294
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "associatedSkills" : [ {
      "skillName" : "French",
      "skillId" : "1000000005432",
      "skillTypeId" : "1000000019013"
    }, {
      "skillName" : "Blueprint",
      "skillId" : "10000000036323",
      "skillTypeId" : "1000000019025"
    }, {
      "skillName" : "Reports",
      "skillId" : "10000000036323",
      "skillTypeId" : "1000000019025"
    } ],
    "departmentId" : "10000000030987"
  }, {
    "associatedSkills" : [ {
      "skillName" : "Workflow",
      "skillId" : "1000000005432",
      "skillTypeId" : "1000000019089"
    }, {
      "skillName" : "English",
      "skillId" : "10000000036323",
      "skillTypeId" : "100000001342"
    } ],
    "departmentId" : "10000000038722"
  }, {
    "associatedSkills" : [ {
      "skillName" : "Malayalam",
      "skillId" : "1000000059234",
      "skillTypeId" : "100000001421"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000003967",
      "skillTypeId" : "100000001423"
    } ],
    "departmentId" : "10000000030294"
  } ]
}

Map Skills in a Department with an Agent

This API modifies skills mapped for an agent in a department

Attributes

Param Name

Data Type

Description

departmentId

long

required

ID of the Department

skillIds

list

optional

Ids of skills to be mapped

POST /api/v1/agents/{agentId}/mapSkills

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/agents/1000000000059/mapSkills?orgId=15157826
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "skillIds" : [ "1000000173047", "1000000173121", "1000000173029" ],
  "departmentId" : "1000000013248"
}'

Response Example

{
  "data" : [ {
    "associatedSkills" : [ {
      "skillName" : "India",
      "skillId" : "1000000173029",
      "skillTypeId" : "1000000173001"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000173121",
      "skillTypeId" : "1000000173013"
    }, {
      "skillName" : "Russia",
      "skillId" : "1000000173047",
      "skillTypeId" : "1000000173001"
    } ],
    "departmentId" : "1000000013248"
  } ]
}

Get Criteria Fields for Skill in a Department

This API returns list of fields supported in criteria for Skills by module

Query Params

Param Name

Data Type

Description

departmentId

long

required

Department Id

module

String

required

Module, Allowed values are tickets,contacts and accounts

GET /api/v1/skills/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skills/criteriaFields?orgId=15157826&departmentId=1000000013248&module=tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Account Name",
      "i18NLabel" : "Account Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Contact Name",
      "i18NLabel" : "Contact Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Email",
      "i18NLabel" : "Email",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Subject",
      "i18NLabel" : "Subject",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Description",
      "i18NLabel" : "Description",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "i18NCondition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is ON HOLD",
        "i18NCondition" : "is ON HOLD",
        "value" : [ "${ONHOLD}" ]
      }, {
        "condition" : "is CLOSED",
        "i18NCondition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case Owner",
      "i18NLabel" : "Ticket Owner",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Created By",
      "i18NLabel" : "Created By",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Modified By",
      "i18NLabel" : "Modified By",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      } ],
      "fieldLabel" : "Created Time",
      "i18NLabel" : "Created Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case On Hold Time",
      "i18NLabel" : "Ticket On Hold Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case Closed Time",
      "i18NLabel" : "Ticket Closed Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      } ],
      "fieldLabel" : "Modified Time",
      "i18NLabel" : "Modified Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Request Id",
      "i18NLabel" : "Ticket Id",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "To Address",
      "i18NLabel" : "To Address",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Thread Count",
      "i18NLabel" : "Number of Threads",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Comment Count",
      "i18NLabel" : "Number of Comments",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "Good", "Bad", "Okay" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "Good", "Bad", "Okay" ]
      }, {
        "condition" : "is received",
        "i18NCondition" : "is received",
        "value" : [ ]
      }, {
        "condition" : "is not received",
        "i18NCondition" : "is not received",
        "value" : [ ]
      }, {
        "condition" : "link provided",
        "i18NCondition" : "link provided",
        "value" : [ ]
      }, {
        "condition" : "link not provided",
        "i18NCondition" : "link not provided",
        "value" : [ ]
      } ],
      "fieldLabel" : "Happiness Rating",
      "i18NLabel" : "Happiness Rating",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "has agents",
        "i18NCondition" : "has agents",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Team",
      "i18NLabel" : "Team",
      "type" : "team"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Due Date",
      "i18NLabel" : "Due Date",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Tags",
      "i18NLabel" : "Tags",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Priority",
      "i18NLabel" : "Priority",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Mode",
      "i18NLabel" : "Channel",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Overdue",
      "i18NLabel" : "Is Overdue",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Escalated",
      "i18NLabel" : "Is Escalated",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Resolution",
      "i18NLabel" : "Resolution",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is Less Than",
        "i18NCondition" : "is Less Than",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is Greater Than",
        "i18NCondition" : "is Greater Than",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Time to Respond",
      "i18NLabel" : "Time to Respond",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Skill",
      "i18NLabel" : "Skill",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      }, {
        "condition" : "contain all of",
        "i18NCondition" : "contain all of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contain any of",
        "i18NCondition" : "contain any of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contain none of",
        "i18NCondition" : "contain none of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Skills",
      "i18NLabel" : "Skills",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Response Overdue",
      "i18NLabel" : "Is Response Overdue",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "during business hours of",
        "i18NCondition" : "during business hours of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "outside business hours of",
        "i18NCondition" : "outside business hours of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "on a holiday of",
        "i18NCondition" : "on a holiday of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "not a holiday of",
        "i18NCondition" : "not a holiday of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Execution Time",
      "i18NLabel" : "Execution Time",
      "type" : "businesshour"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "Public", "Private" ]
      } ],
      "fieldLabel" : "Recent Comment Type",
      "i18NLabel" : "Recent Comment Type",
      "type" : "commenttype"
    }, {
      "availableConditions" : [ {
        "condition" : "contains one of the following words",
        "i18NCondition" : "contains one of the following words",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains none of the following words",
        "i18NCondition" : "contains none of the following words",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains the string",
        "i18NCondition" : "contains the string",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "does not contain the string",
        "i18NCondition" : "does not contain the string",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "has @ mentions of",
        "i18NCondition" : "has @ mentions of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Recent Comment",
      "i18NLabel" : "Recent Comment",
      "type" : "comment"
    } ]
  } ]
}

SkillTypes

SkillType is a Category for grouping skills

Example

{ "modifiedTime" : "2020-07-23T12:36:44.544Z", "associatedSkills" : [ { "skillName" : "India", "skillId" : "1000000173029", "skillStatus" : "ACTIVE" }, { "skillName" : "Russia", "skillId" : "1000000173047", "skillStatus" : "ACTIVE" } ], "createdBy" : "1000000000059", "departmentId" : "1000000013248", "name" : "Country", "createdTime" : "2020-07-23T12:36:44.544Z", "modifiedBy" : "1000000000059", "id" : "1000000173001" }

Create Skill Type

This API Creates a Skill Type

Attributes

Param Name

Data Type

Description

name

String

required

Name of the skilltype

departmentId

long

required

departmentId of the Skill Type

POST /api/v1/skillTypes

OAuth Scope

Desk.settings.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/skillTypes
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "departmentId" : "1000000013248",
  "name" : "Country"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:36:44.544Z",
  "associatedSkills" : [ ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Country",
  "createdTime" : "2020-07-23T12:36:44.544Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173001"
}

View Skill Type

This API Gets the details of a Skill Type

GET /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skillTypes/1000000173001
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-23T12:36:44.544Z",
  "associatedSkills" : [ {
    "skillName" : "India",
    "skillId" : "1000000173029",
    "skillStatus" : "ACTIVE"
  }, {
    "skillName" : "Russia",
    "skillId" : "1000000173047",
    "skillStatus" : "ACTIVE"
  } ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Country",
  "createdTime" : "2020-07-23T12:36:44.544Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173001"
}

Update a Skill Type

This API Updates a Skill Type

Attributes

Param Name

Data Type

Description

name

String

optional

Name of the skilltype

PATCH /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/skillTypes/4000003016645
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "name" : "Product"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:39:11.776Z",
  "associatedSkills" : [ ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Product",
  "createdTime" : "2020-07-23T12:39:11.776Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173019"
}

Delete a Skill Type

This API Deletes a Skill Type

DELETE /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/skillTypes/4000003016645
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

List all Skill Types

This API Lists all Skill Types in a department

Query Params

Param Name

Data Type

Description

departmentId

long

optional

Department Id

from

integer

optional

Index number, starting from which the skills must be listed

limit

integer

optional,
range : 1-100

Number of skilltypes to list, allowed minimum value 1, maximum value 100,default is 100

mappedSkillsStatus

String

optional

Filter skill types by associated skills status, allowed values ACTIVE and INACTIVE

GET /api/v1/skillTypes

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skillTypes?departmentId=4000003016008
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-07-23T12:36:44.544Z",
    "associatedSkills" : [ {
      "skillName" : "India",
      "skillId" : "1000000173029",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Russia",
      "skillId" : "1000000173047",
      "skillStatus" : "ACTIVE"
    } ],
    "mappedSkillsStatus" : [ "ACTIVE" ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Country",
    "createdTime" : "2020-07-23T12:36:44.544Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173001"
  }, {
    "modifiedTime" : "2020-07-23T12:38:59.455Z",
    "associatedSkills" : [ {
      "skillName" : "English",
      "skillId" : "1000000173097",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Malayalam",
      "skillId" : "1000000173145",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000173121",
      "skillStatus" : "INACTIVE"
    } ],
    "mappedSkillsStatus" : [ "INACTIVE", "ACTIVE" ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Language",
    "createdTime" : "2020-07-23T12:38:59.455Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173013"
  }, {
    "modifiedTime" : "2020-07-23T12:39:47.900Z",
    "associatedSkills" : [ ],
    "mappedSkillsStatus" : [ ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Product",
    "createdTime" : "2020-07-23T12:39:11.776Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173019"
  }, {
    "modifiedTime" : "2020-07-23T12:38:53.429Z",
    "associatedSkills" : [ ],
    "mappedSkillsStatus" : [ ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Region",
    "createdTime" : "2020-07-23T12:38:53.429Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173007"
  } ]
}

SkillConfiguration

Department Level Configurations for Skill Stamping

ATTRIBUTES

Attribute Name

Data Type

Description

departmentId

long

ID of the Department

attachSkillsOption

string

Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER

autoSkillStamping

string

This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE

Example

{ "autoSkillStamping" : "INACTIVE", "departmentId" : "1000000013248", "attachSkillsOption" : "AT_FIRST" }

Get Skill Configuration

This API gets Configuration of Skill in a Department

Query Params

Param Name

Data Type

Description

departmentId

long

required

Department Id

GET /api/v1/skillConfiguration

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/skillConfiguration?departmentId=1000000013248
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "autoSkillStamping" : "ACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_THE_END"
}

Update Skill Configuration

This API updates Configuration of Skill in a Department

Attributes

Param Name

Data Type

Description

departmentId

long

optional

ID of the Department

attachSkillsOption

string

optional,
max chars : 100

Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER

autoSkillStamping

string

optional,
max chars : 100

This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE

PATCH /api/v1/skillConfiguration

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/skillConfiguration
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "autoSkillStamping" : "INACTIVE", "departmentId" : "1000000013248", "attachSkillsOption" : "AT_FIRST" }'

Response Example

{
  "autoSkillStamping" : "INACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_FIRST"
}

RoutingPreference

Common Configurations for Routing Rules

ATTRIBUTES

Attribute Name

Data Type

Description

departmentId

long

department Id

isThresholdEnabled

boolean

Used to enable/disable ticket threshold for Round Robin

thresholdLimit

integer

Threshold Per Agent, Range 1-200,thresholdEnabled has to be True to Update this limit

assignBacklog

boolean

Will bulk-assign tickets that were created when agents were unavailable.

backLogLimit

integer

Max. number of backlog tickets that can be bulk-assigned to an agent. Range 1-50

assignBacklogsBy

String

Assign Backlogs Based on Due Date or Created Time, Allowed values DUEDATE and CREATEDTIME

assignToOfflineAgents

boolean

Will include mail-channel offline agents also while assigning tickets.

freshTicketAssignMode

String

Fresh Ticket Assignment Mode, allowed values are IMMEDIATE,MOVE_TO_BACKLOG

Example

{ "assignBacklog" : true, "assignToOfflineAgents" : true, "thresholdLimit" : "40", "backLogLimit" : "5", "isThresholdEnabled" : true, "departmentId" : "1000000013248", "assignBacklogsBy" : "DUEDATE", "freshTicketAssignMode" : "IMMEDIATE" }

Get Routing Preferences

This API is used to Get the Routing Preferences for a Department

Query Params

Param Name

Data Type

Description

departmentId

long

required

Department Id

GET /api/v1/routingPreferences

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/routingPreferences?departmentId=1000000013248
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "assignBacklog" : true,
  "assignToOfflineAgents" : true,
  "thresholdLimit" : "40",
  "backLogLimit" : "5",
  "isThresholdEnabled" : true,
  "departmentId" : "1000000013248",
  "assignBacklogsBy" : "DUEDATE",
  "freshTicketAssignMode" : "IMMEDIATE"
}

Update Routing Preferences

This API is used to Update the Routing Preferences for a Department

Attributes

Param Name

Data Type

Description

departmentId

long

optional

department Id

isThresholdEnabled

boolean

optional

Used to enable/disable ticket threshold for Round Robin

thresholdLimit

integer

optional,
range : 1-200

Threshold Per Agent, Range 1-200,thresholdEnabled has to be True to Update this limit

assignBacklog

boolean

optional

Will bulk-assign tickets that were created when agents were unavailable.

backLogLimit

integer

optional,
range : 1-50

Max. number of backlog tickets that can be bulk-assigned to an agent. Range 1-50

assignBacklogsBy

String

optional

Assign Backlogs Based on Due Date or Created Time, Allowed values DUEDATE and CREATEDTIME

assignToOfflineAgents

boolean

optional

Will include mail-channel offline agents also while assigning tickets.

freshTicketAssignMode

String

optional

Fresh Ticket Assignment Mode, allowed values are IMMEDIATE,MOVE_TO_BACKLOG

PATCH /api/v1/routingPreferences

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/routingPreferences
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

-d'{ "assignBacklog" : true, "isThresholdEnabled" : "true", "backLogLimit" : "22", "departmentId" : "1000000013248" }'

Response Example

{
  "assignBacklog" : true,
  "assignToOfflineAgents" : true,
  "thresholdLimit" : "40",
  "backLogLimit" : "22",
  "isThresholdEnabled" : true,
  "departmentId" : "1000000013248",
  "assignBacklogsBy" : "DUEDATE",
  "freshTicketAssignMode" : "IMMEDIATE"
}

Recycle Bin

The Recycle Bin is the location where deleted resources, such as tickets, contacts, tasks, and time entries among others, are temporarily stored. From this location, users can retrieve resources that may have been accidentally deleted.

ATTRIBUTES

Attribute Name

Data Type

Description

ids

list

Array containing the IDs of the resources.

isChildNeedToBeRestored

boolean

Key that denotes whether the child resources must be restored or not.

departmentId
see documentation

long

ID of the department to which the deleted resources belong.

Example

{ "isChildNeedToBeRestored" : "true", "departmentId" : "4000000013244", "ids" : [ "232323", "3213123", "232", "4000000056156" ] }

List deleted resources

This API lists a particular number of deleted resources, based on the limit specified.

Query Params

Param Name

Data Type

Description

from

integer

optional,
range : >=0

Index number, starting from which the resources must be fetched.

limit

integer

optional,
range : 1-100

Number of resources to list. The default value is 10 and the maximum value supported is 100.

departmentId
see documentation

long

optional

ID of the department to which the deleted resources belong.

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: name, type, department, deletedBy, or deletedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Additional information related to the resources. Values allowed are: department and deletedBy. You can pass multiple values by separating them with commas in the API request.

module

String

optional

Filter by a specific module: accounts, contacts, tickets, tasks, timeEntry, calls, events, contracts, products, topics, or solutions

GET api/v1/recycleBin

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/recyleBin?include=deletedBy,department
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "displayName" : "Sample display name",
    "departmentId" : null,
    "deletedById" : "4000000000059",
    "id" : "4000000046163",
    "type" : "Attachments",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046093",
    "type" : "Calls",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000017184",
    "type" : "Tickets",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046029",
    "type" : "Tickets",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : null,
    "deletedById" : "4000000000059",
    "id" : "4000000019005",
    "type" : "Contacts",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046131",
    "type" : "Events",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046111",
    "type" : "Tasks",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046153",
    "type" : "Time Entry",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  } ]
}

Restore deleted resources

This API restores the deleted resources specified in the API request. Additionally, the parent resources are also restored.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the resources to restore

isChildNeedToBeRestored

boolean

optional

Key that denotes whether the child resources must be restored or not.

POST api/v1/recycleBin/restore

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/restore
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "isChildNeedToBeRestored" : "true",
  "ids" : [ "232323", "400000005634", "232", "4000000056156" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000056156",
    "errors" : null
  }, {
    "success" : false,
    "id" : "232323",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "400000005634",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  }, {
    "success" : false,
    "id" : "232",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Restore all resources from Recycle Bin

This API restores all deleted resources from the Recycle Bin.

POST api/v1/recycleBin/restoreAll

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/recyleBin/restoreAll
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

Delete resources from Recycle Bin

This API permanently deletes the resources specified in the API request. Additionally, the child resources are also permanently deleted.

Attributes

Param Name

Data Type

Description

ids

list

required

Array containing the IDs of the resources to delete.

POST api/v1/recycleBin/delete

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/delete
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{
  "ids" : [ "232323", "3213123", "40000000561232", "4000000056156" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000056156",
    "errors" : null
  }, {
    "success" : false,
    "id" : "232323",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "3213123",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "40000000561232",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Delete all resources from Recycle Bin

This API permanently deletes all resources from the Recycle Bin.

POST api/v1/recycleBin/deleteAll

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/recyleBin/deleteAll
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example